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Introduction 


This manual gives the Windows-application developer general as well as detailed 
information about Windows functions, messages, data types, Resource-Compiler 
statements, assembly-language macros, and file formats. It does not attempt to ex- 
plain how to create a Windows application. Rather, this manual provides detailed 
descriptions of each component of the Windows application program interface 
(API) for readers who already have a basic understanding of Windows program- 
ming. 


This manual is divided into two volumes. Volume 1 contains reference informa- 
tion describing the Windows functions and messages. 


Volume 2 contains reference material for other components of the Windows API. 
It contains the following nine chapters and five appendixes: 


Chapter 7, “Data Types and Structures,” contains a table of data types and an al- 
phabetical list of structures found in Windows. 


Chapter 8, “Resource Script Statements,” describes the statements that define 
resources which the Resource Compiler adds to an application’s executable file. 
The statements are arranged according to functional groups. 


Chapter 9, “File Formats,” describes the formats of five types of files: bitmap 
files, icon resource files, cursor resource files, clipboard files, and metafiles. 
Each description gives the general file structure and information about specific 
parts of the file. 


Chapter 10, “Module-Definition Statements,” describes the statements contained 
in the module-definition file that defines the application’s contents and system re- 
quirements for the LINK program. 


Chapter 11, “Binary and Ternary Raster-Operation Codes,” describes the raster 
operations used for line output and those used for bitmap output. 


Chapter 12, “Printer Escapes,” lists the printer escapes that are available in 
Windows. 


Chapter 13, “Assembly-Language Macros Overview,” categorizes and briefly de- 
scribes the Windows assembly-language macros which provide a simplified inter- 
face to the function and segment conventions of high-level languages. 


Chapter 14, “Assembly-Language Macros Directory,” lists the assembly-lan- 
guage macros alphabetically and, for each macro, provides a detailed description 
and one or more examples of how to use it in a program. 


Chapter 15, “Windows DDE Protocol Definition,” contains an alphabetical 
listing and description of the Windows messages which comprise the Windows 
Dynamic Data Exchange protocol. 
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Appendix A, “Virtual-Key Codes,” lists the symbolic names and hexadecimal 
values of Windows virtual-key codes and includes a brief description of each key. 


Appendix B, “RC Diagnostic Messages,” contains a listing of Resource Com- 
piler error messages and provides a brief description of each message. 


Appendix C, “Windows Debugging Messages,” contains a listing of Windows de- 
bugging messages and provides a brief description of each message. 


Appendix D, “Character Tables,” shows the layout of the ANSI character set and 
the IBM PC Extended Character set. 


Appendix E, “32-Bit Memory Management DLL,” describes how to implement a 
32-bit flat memory model for your application. 
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Document Conventions 


Throughout this manual, the term “DOS” refers to both MS-DOS® and PC- 
DOS, except when noting features that are unique to one or the other. 


The following document conventions are used throughout this manual: 


Convention Description of Convention 


Bold text Bold letters indicate a specific term or punctua- 
tion mark intended to be used literally: 
language key words or functions (such as 
EXETYPE or CreateWindow), DOS com- 
mands, and command-line options (such as 
/Zi). You must type these terms and punctua- 
tion marks exactly as shown. However, the use 
of uppercase or lowercase letters is not always 
significant. For instance, you can invoke the 
linker by typing either LINK, link, or Link at 
the DOS prompt. 


() In syntax statements, parentheses enclose one 
or more parameters that you pass to a function. 


Italic text Words in italics indicate a placeholder; you are 
expected to provide the actual value. For ex- 
ample, the following syntax for the 
SetCursorPos function indicates that you must 
substitute values for the X and Y coordinates, 
separated by a comma: 


SetCursorPos(X, Y) 


Monospaced type Code examples are displayed in a nonpropor- 
tional typeface. 
BEGIN Vertical ellipses in program examples indicate 


that a portion of the program is omitted. 


END 
Ellipses following an item indicate that more 
items having the same form may appear. In the 
following example, the horizontal ellipses indi- 


cate that you can specify more than one 
breakaddress for the g command: 


g ([=startaddress]] [breakaddress]... 
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Convention Description of Convention 
L] Double brackets enclose optional fields or para- 


meters in command lines and syntax 
statements. In the following example, option 
and executable-file are optional parameters of 
the RC command: 


RC [option] filename [[executable-file]| 


A vertical bar indicates that you may enter one 
of the entries shown on either side of the bar. 
The following command-line syntax illustrates 
the use of a vertical bar: 


DB [address | range] 


The bar indicates that following the DB (dump 
bytes) command, you can specify either an 
address or a range. 


“oo 


Quotation marks set off terms defined in the 
text. 


{ } Curly braces indicate that you must specify 
one of the enclosed items. 


SMALL CAPITAL LETTERS Small capital letters indicate the names of keys 
and key sequences, such as: 


ALT + SPACEBAR 


A box containing a Microsoft Windows ver- 
sion number indicates that a function, message, 
or data structure is compatible only with the 
specified version and later versions. 


Microsoft Windows Software Development Kit Documentation Set 


Throughout this documentation set “SDK” refers specifically to the Microsoft 
Windows Software Development Kit and its contents. The SDK includes the fol- 
lowing manuals: 


Title Contents 
Installation and Provides an orientation to the SDK, explains how to 
Update Guide install the SDK software, and highlights the changes 


for version 3.0. 
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Title 


Guide to Programming 


Tools 


Reference 


System Application 
Architecture, Common 
User Access: 
Advanced Interface 
Design Guide 


Contents 


Explains how to write Windows applications, and 
provides sample applications that you can use as 
templates for writing your own programs. The 
Guide to Programming also addresses some 
advanced Windows programming topics. 


Explains how to use the software-development tools 
you’ll need to build Windows applications, such as 
debuggers and specialized SDK editors. 


Is a comprehensive guide to all the details of the 
Microsoft Windows application program interface 
(API). The Reference lists in alphabetical order all 
the current functions, messages, and data structures 
of the API, and provides extensive overviews on 
how to use the API. 


Provides guidelines and recommendations for writ- 
ing programs that look and act consistently with 
other Microsoft Windows applications. 


Patt || General Reference 


Part 3 provides general reference information on components of the Windows 
application programming interface that are in addition to the functions and mes- 
sages described in the preceding parts. 
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This chapter describes the data types and structures used by Microsoft Windows 
functions and messages. It contains two parts: a table of data types and a list of 
Windows data structures, each arranged alphabetically. 


7.1 Data Types 


The data types in the following list are key words that define the size and 
meaning of parameters and return values associated with Windows functions. 
This list contains character, integer, and Boolean types, pointer types, and han- 
dles. The character, integer, and Boolean types are common to most C compilers. 
Most of the pointer-type names begin with either a P prefix (for short pointers) or 
an LP prefix (for long pointers). A short pointer accesses data within the current 
data segment; a long pointer contains a 32-bit segment/offset value. A Windows 
application uses a handle to refer to a resource that has been loaded into memory. 
Windows provides access to these resources through internally maintained tables 
that contain individual entries for each handle. Each entry in the handle table con- 
tains the address of the resource and a means of identifying the resource type. 
The Windows data types are defined in the following list: 


Type Definition 

BOOL 16-bit Boolean value. 

BYTE Unsigned 8-bit integer. 

char ASCII character or a signed 8-bit in- 
teger. 

DWORD Unsigned 32-bit integer or a seg- 


ment/offset address. 


FAR Data-type attribute that can be used to 
create a long pointer. 


FARPROC Long pointer to a function obtained by 
calling the MakeProcInstance func- 
tion. 
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Type Definition 


GLOBALHANDLE Handle to global memory. It is a 16-bit 
index to a block of memory allocated 
from the system’s global heap. 


HANDLE General handle. It represents a 16-bit 
index to a table entry that identifies pro- 
gram data. 


HBITMAP Handle to a physical bitmap. It is a 16- 
bit index to GDI’s physical drawing 
objects. 


HBRUSH Handle to a physical brush. It is a 16-bit 
index to GDI’s physical drawing ob- 
jects. 


HCURSOR Handle to a cursor resource. It is a 16- 
bit index to a resource-table entry. 


HDC Handle to a display context. It is a 16- 
bit index to GDI’s device-context 
tables. 


HFONT Handle to a physical font. It is a 16-bit 
index to GDI’s physical drawing ob- 
jects. 


HICON Handle to an icon resource. It is a 16- 
bit index to a resource-table entry. 


HMENU Handle to a menu resource. It is a 16- 
bit index to a resource-table entry. 


HPALETTE Handle to a logical palette. It is a 16-bit 
index to GDI’s physical drawing ob- 
jects. 


HPEN Handle to a physical pen. It is a 16-bit 
index to GDI’s physical drawing ob- 
jects. 


HRGN Handle to a physical region. It is a 16- 
bit index to GDI’s physical drawing 
objects. 


HSTR Handle to a string resource. It is a 16- 
bit index to a resource-table entry. 


int Signed 16-bit integer. 


Type 
LOCALHANDLE 


long 
LONG 
LPBITMAP 


LPBITMAPCOREHEADER 
LPBITMAPCOREINFO 
LPBITMAPFILEHEADER 
LPBITMAPINFO 
LPBITMAPINFOHEADER 
LPCOMPAREITEMSTRUCT 
LPCREATESTRUCT 
LPDELETEITEMSTRUCT 
LPDRAWITEMSTRUCT 
LPHANDLETABLE 


LPINT 
LPLOGBRUSH 


LPLOGFONT 


LPLOGPALETTE 
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Definition 


Handle to local memory. It is a 16-bit 
index to a block of memory allocated 
from the application’s local heap. 


Signed 32-bit integer. 
Signed 32-bit integer. 


Long pointer to a BITMAP data struc- 
ture. 


Long pointer to a BITMAPCORE- 
HEADER data structure. 


Long pointer to a BITMAPCORE- 
INFO data structure. 


Long pointer to a BITMAPFILE- 
HEADER data structure. 


Long pointer to a BITMAPINFO data 
structure. 


Long pointer to a BITMAPINFO- 
HEADER data structure. 


Long pointer to a COMPAREITEM- 
STRUCT data structure. 


Long pointer to a CREATESTRUCT 
data structure. 


Long pointer to a DELETEITEM- 
STRUCT data structure. 


Long pointer to a DRAWITEM- 
STRUCT data structure. 


Long pointer to a HANDLETABLE 
data structure. 


Long pointer to a signed 16-bit integer. 


Long pointer to a LOGBRUSH data 
structure. 


Long pointer to a LOGFONT data 
structure. 


Long pointer to a LOGPALETTE data 
structure. 
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Type 
LPLOGPEN 


LPMEASUREITEMSTRUCT 


LPMETAFILEPICT 


LPMSG 
LPOFSTRUCT 


LPPAINTSTRUCT 


LPPALETTEENTRY 


LPPOINT 
LPRECT 
LPRESOURCELIST 


LPSTR 
LPTEXTMETRIC 


LPVOID 
LPWNDCLASS 


NEAR 


NPSTR 
PINT 
PSTR 
PWORD 


short 


Definition 


Long pointer to a LOGPEN data struc- 
ture. 


Long pointer to a MEASURE- 
ITEMSTRUCT data structure. 


Long pointer to a METAFILEPICT 
data structure. 


Long pointer to a MSG data structure. 


Long pointer to an OFSTRUCT data 
structure. 


Long pointer to a PAINTSTRUCT 
data structure. 


Long pointer to a PALETTEENTRY 
data structure. 


Long pointer to a POINT data structure. 
Long pointer to a RECT data structure. 


Long pointer to one or more 
RESOURCESTRUCT data structures. 


Long pointer to a character string. 


Long pointer to a TEXTMETRIC data 
structure. 


Long pointer to an undefined data type. 


Long pointer to a WNDCLASS data 
structure. 


Data-type attribute that can be used to 
create a short pointer. 


Near pointer to a character string. 
Pointer to a signed 16-bit integer. 
Pointer to a character string. 

Pointer to an unsigned 16-bit integer. 


Signed 16-bit integer. 
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Type Definition 


void Empty value. It is used with a function 
to specify no return value. 


WORD Unsigned 16-bit integer. 


7.2 Data Structures 


This section lists data structures that are used by Windows. The data structures 
are presented in alphabetical order. The structure definition is given, followed by 
a description of each field. 


BITMAP 


BITMAP 


Bitmap Data Structure 


Comments 


The BITMAP structure defines the height, width, color format, and bit values of a logical 


bitmap. 


typedef struct tagBITMAP { 


short 
short 
short 
short 
BYTE 
BYTE 
LPSTR 
} BITMAP; 


bmType; 
bmWidth; 
bmHeight; 
bmWidthBytes; 
bmPlanes; 
bmBitsPixel; 
bmBits; 


The BITMAP structure has the following fields: 


Field 
bmType 


bmWidth 
bmHeight 


bmWidthBytes 


bmPlanes 


bmBitsPixel 


bmBits 


Description 


Specifies the bitmap type. For logical bitmaps, the bmType field 
must be zero. 


Specifies the width of the bitmap (in pixels). The width must be 
greater than zero. 


Specifies the height of the bitmap (in raster lines). The height 
must be greater than zero. 


Specifies the number of bytes in each raster line. This value 
must be an even number since the graphics device interface 
(GDI) assumes that the bit values of a bitmap form an array of 
integer (two-byte) values. In other words, bm WidthBytes x 8 
must be the next multiple of 16 greater than or equal to the 
bmWidth field. 


Points to the number of color planes in the bitmap. 


Points to the number of adjacent color bits on each plane needed 
to define a pixel. 


Points to the location of the bit values for the bitmap. The 
bmBits field must be a long pointer to an array of character (one- 
byte) values. 


The currently used bitmap formats are monochrome and color. The monochrome bitmap 
uses a one-bit, one-plane format. Each scan is a multiple of 16 bits. 
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Scans are organized as follows for a monochrome bitmap of height n: 


Scan @ 
Scan 1 


Scan n-2 
Scan n-1l 


The pixels on a monochrome device are either black or white. If the corresponding bit in 
the bitmap is 1, the pixel is turned on (white); if the corresponding bit in the bitmap is 
zero, the pixel is turned off (black). 


All devices that have the RC_BITBLT bit set in the device capabilities support bitmaps. 


Each device has its own unique color format. In order to transfer a bitmap from one device 
to another, use GetDIBits and SetDIBits. 


See Also The CreateBitmapIndirect and GetObject functions in Chapter 4, “Functions Directory,” 
in Reference, Volume 1. 


BITMAPCOREHEADER 


Device-Independent Bitmap Format Information 


The BITMAPCOREHEADER structure contains information about the dimensions and 
color format of a device-independent bitmap that is compatible with Microsoft OS/2 Pre- 
sentation Manager versions 1.1 and 1.2 bitmaps. 


typedef struct tagBITMAPCOREHEADER { 
DWORD  bcSize; 
WORD bcWidth; 
WORD bcHeight; 
WORD bcPlanes; 
WORD bcBitCount; 
} BITMAPCOREHEADER; 


The BITMAPCOREHEADER structure has the following fields: 


Field Description 

bcSize Specifies the number of bytes required by the BITMAP- 
COREHEADER structure. 

beWidth Specifies the width of the bitmap in pixels. 


beHeight Specifies the height of the bitmap in pixels. 
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Comments 


Field Description 

bePlanes Specifies the number of planes for the target device and must be set 
to 1. 

bcBitCount Specifies the number of bits per pixel. This value must be 1, 4, 8, or 
24. 


The BITMAPCOREINFO data structure combines the BITMAPCOREHEADER struc- 
ture and a color table to provide a complete definition of the dimensions and colors of a 
device-independent bitmap. See the description of the BITMAPCOREINFO data struc- 
ture for more information about specifying a device-independent bitmap. 


An application should use the information stored in the beSize field to locate the color 
table ina BITMAPCOREINFO data structure with a method such as the following: 


pColor = ((LPSTR) pBitmapCoreInfo + (WORD) (pBitmapCoreInfo -> bcSize)) 


BITMAPCOREINFO 


Device-Indpendent Bitmap Information 


Comments 


The BITMAPCOREINFO structure fully defines the dimensions and color information 
for a device-independent bitmap that is compatible with Microsoft OS/2 Presentation 
Manager versions 1.1 and 1.2 bitmaps. 


typedef struct _BITMAPCOREINFO { 
BITMAPCOREHEADER bmciHeader; 
RGBTRIPLE bmciColors(]; 
} BITMAPCOREINFO; 


The BITMAPCOREINFO structure contains the following fields: 


Field Description 


bmciHeader Specifies a BITMAPCOREHEADER data structure that contains 
information about the dimensions and color format of a device-inde- 
pendent bitmap. 


bmciColors Specifies an array of RGBTRIPLE data structures that define the 
colors in the bitmap. 


An OS/2 Presentation Manager device-independent bitmap consists of two distinct parts: 
a BITMAPCOREINFO data structure that describes the dimensions and colors of the bit- 
map, and an array of bytes which define the pixels of the bitmap. The bits in the array are 
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packed together, but each scan line must be zero-padded to end on a LONG boundary. Seg- 
ment boundaries can appear anywhere in the bitmap, however. The origin of the bitmap is 
the lower-left corner. 


The bcBitCount field of the BBTMAPCOREHEADER structure determines the number 
of bits which define each pixel and the maximum number of colors in the bitmap. This 
field may be set to any of the following values: 


Value Meaning 


1 The bitmap is monochrome, and the bmciColors field must contain two 
entries. Each bit in the bitmap array represents a pixel. If the bit is clear, 
the pixel is displayed with the color of the first entry in the bmciColors 
table; if the bit is set, the pixel has the color of the second entry in the 
table. 


4 The bitmap has a maximum of 16 colors, and the bmciColors field con- 
tains 16 entries. Each pixel in the bitmap is represented by a four-bit 
index into the color table. 


For example, if the first byte in the bitmap is Ox1F, then the byte repre- 
sents two pixels. The first pixel contains the color in the second table 
entry, and the second pixel contains the color in the 16th table entry. 


8 The bitmap has a maximum of 256 colors, and the bmciColors field 
contains 256 entries. In this case, each byte in the array represents a 
single pixel. 


24 The bitmap has a maximum of 274 colors. The bmciColors field is 
NULL, and each three bytes in the bitmap array represents the relative 
intensities of red, green, and blue, respectively, of a pixel. 


The colors in the bmciColors table should appear in order of importance. 


Alternatively, for functions that use device-independent bitmaps, the bmciColors field can 
be an array of 16-bit unsigned integers that specify an index into the currently realized logi- 
cal palette instead of explicit RGB values. In this case, an application using the bitmap 
must call device-independent bitmap functions with the wUsage parameter set to 
DIB_PAL_COLORS. 
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Note The bmeiColors field should not contain palette indexes if the bitmap is to be stored in a file or 
transferred to another application. Unless the application uses the bitmap exclusively and under its 
complete control, the bitmap color table should contain explicit RGB values. 


BITMAPFILEHEADER 


Bitmap File Information 


The BITMAPFILEHEADER data structure contains information about the type, size, 
and layout of a device-independent bitmap (DIB) file. 


typedef struct tagBITMAPFILEHEADER { 
WORD bfType; 
DWORD bfSize; 
WORD bfReservedl; 
WORD bfReserved2; 
DWORD bfOffBits; 
} BITMAPFILEHEADER; 


The BITMAPFILEHEADER data structure contains the following fields: 


Field Description 

bfType Specifies the type of file. It must be BM. 

bfSize Specifies the size in DWORDs of the file. 

bfReserved1 Is reserved and must be set to zero. 

bfReserved2 Is reserved and must be set to zero. 

bfOffBits Specifies in bytes the offset from the BITMAPFILEHEADER 


of the actual bitmap in the file. 


Comments A BITMAPINFO or BITMAPCOREINFO data structure immediately follows the 
BITMAPFILEHEADER structure in the DIB file. 


BITMAPINFO 
Device-Indpendent Bitmap Information 


The BITMAPINFO structure fully defines the dimensions and color information for a 
Windows 3.0 device-independent bitmap. 
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typedef struct tagBITMAPINFO { 
BITMAPINFOHEADER bmiHeader; 
RGBQUAD bmiColors[1]; 
} BITMAPINFO; 
The BITMAPINFO structure contains the following fields: 
Field Description 
bmiHeader Specifies a BITMAPINFOHEADER data structure that con- 
tains information about the dimensions and color format of a 
device-independent bitmap. 
bmiColors Specifies an array of RGBQUAD data structures that define the 
colors in the bitmap. 
Comments A Windows 3.0 device-independent bitmap consists of two distinct parts: a BITMAP- 


INFO data structure that describes the dimensions and colors of the bitmap, and an array 
of bytes that define the pixels of the bitmap. The bits in the array are packed together, but 
each scan line must be zero-padded to end on a LONG boundary. Segment boundaries can 
appear anywhere in the bitmap, however. The origin of the bitmap is the lower-left corner. 


The biBitCount field of the BITMAPINFOHEADER structure determines the number 
of bits which define each pixel and the maximum number of colors in the bitmap. This 
field may be set to any of the following values: 


Value Meaning 


1 The bitmap is monochrome, and the bmiColors field must contain 
two entries. Each bit in the bitmap array represents a pixel. If the bit 
is Clear, the pixel is displayed with the color of the first entry in the 
bmiColors table; if the bit is set, the pixel has the color of the second 
entry in the table. 


4 The bitmap has a maximum of 16 colors, and the bmiColors field 
contains up to 16 entries. Each pixel in the bitmap is represented by a 
four-bit index into the color table. 


For example, if the first byte in the bitmap is Ox1F, then the byte rep- 
resents two pixels. The first pixel contains the color in the second 
table entry, and the second pixel contains the color in the 16th table 
entry. 


8 The bitmap has a maximum of 256 colors, and the bmiColors field 
contains up to 256 entries. In this case, each byte in the array repre- 
sents a single pixel. 


BITMAPINFOHEADER 7-12 


Value Meaning 


24 The bitmap has a maximum of 2*4 colors. The bmiColors field is 
NULL, and each three bytes in the bitmap array represents the rela- 
tive intensities of red, green, and blue, respectively, of a pixel. 


The biClrUsed field of the BITMAPINFOHEADER structure specifies the number of 
color indexes in the color table actually used by the bitmap. If the biClrUsed field is set to 
0, the bitmap uses the maximum number of colors corresponding to the value of the biBit- 
Count field. 


The colors in the bmiColors table should appear in order of importance. 


Alternatively, for functions that use device-independent bitmaps, the bmiColors field can 
be an array of 16-bit unsigned integers that specify an index into the currently realized logi- 
cal palette instead of explicit RGB values. In this case, an application using the bitmap 
must call device-independent bitmap functions with the wUsage parameter set to 
DIB_PAL_COLORS. 


Note The bmiColors field should not contain palette indices if the bitmap is to be stored in a file or 
transferred to another application. Unless the application uses the bitmap exclusively and under its 
complete control, the bitmap color table should contain explicit RGB values. 


BITMAPINFOHEADER 


Device-Independent Bitmap Format Information 


The BITMAPINFOHEADER structure contains information about the dimensions and 
color format of a Windows 3.0 device-independent bitmap. 


typedef struct tagBITMAPINFOHEADER{ 
DWORD biSize; 
DWORD biWidth; 
DWORD biHeight; 
WORD biPlanes; 
WORD biBitCount 
DWORD biCompression; 
DWORD biSizelImage; 
DWORD biXPelsPerMeter; 
DWORD biYPelsPerMeter; 
DWORD biClrUsed; 
DWORD biClrImportant; 
} BITMAPINFOHEADER; 


The BITMAPINFOHEADER structure has the following fields: 
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Field 
biSize 


biWidth 
biHeight 


biPlanes 
biBitCount 


biCompression 


biSizeImage 


biXPelsPerMeter 


biYPelsPerMeter 


BITMAPINFOHEADER 


Description 


Specifies the number of bytes required by the BITMAP- 
INFOHEADER structure. 


Specifies the width of the bitmap in pixels. 
Specifies the height of the bitmap in pixels. 


Specifies the number of planes for the target device and 
must be set to 1. 


Specifies the number of bits per pixel. This value must be 
1, 4, 8, or 24. 


Specifies the type of compression for a compressed bit- 
map. It can be one of the following values: 


Value Meaning 

BI_RGB Specifies that the bitmap is not com- 
pressed. 

BI_RLE8 Specifies a run-length encoded for- 


mat for bitmaps with 8 bits per pixel. 
The compression format is a two- 
byte format consisting of a count byte 
followed by a byte containing a color 
index. See the following “Com- 
ments” section for more information. 


BI_RLE4 Specifies a run-length encoded for- 
mat for bitmaps with 4 bits per pixel. 
The compression format is a two- 
byte format consisting of a count byte 
followed by two word-length color in- 
dexes. See the following 
“Comments” section for more infor- 
mation. 


Specifies the size in bytes of the image. 


Specifies the horizontal resolution in pixels per meter of 
the target device for the bitmap. An application can use this 
value to select a bitmap from a resource group that best 
matches the characteristics of the current device. 


Specifies the vertical resolution in pixels per meter of the 
target device for the bitmap. 


BITMAPINFOHEADER 


Commenis 


Field 
biClrUsed 


biClrImportant 
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Description 


Specifies the number of color indexes in the color table ac- 
tually used by the bitmap. If this value is 0, the bitmap uses 
the maximum number of colors corresponding to the value 
of the biBitCount field. See the description of the 
BITMAPINFO data structure earlier in this chapter for 
more information on the maximum sizes of the color table. 


If biClr Used is nonzero, then the biClrUsed field speci- 
fies the actual number of colors which the graphics engine 
or device driver will access if the biBitCount field is less 
than 24. If the biBitCount field is set to 24, the biClrUsed 
field specifies the size of the reference color table used to 
optimize performance of Windows color palettes. 


If the bitmap is a “packed” bitmap (that is, a bitmap in 
which the bitmap array immediately follows the BITMAP- 
INFO header and which is referenced by a single pointer), 
the biClrUsed field must be set to 0 or to the actual size of 
the color table. 


Specifies the number of color indexes that are considered 
important for displaying the bitmap. If this value is 0, then 
all colors are important. 


The BITMAPINFO data structure combines the BITMAPINFOHEADER structure and 
a color table to provide a complete definition of the dimensions and colors of a Windows 
3.0 device-independent bitmap. See the description of the BITMAPINFO data structure 
for more information about specifying a Windows 3.0 device-independent bitmap. 


An application should use the information stored in the biSize field to locate the color 
table in a BITMAPINFO data structure with a method such as the following: 


pColor = ((LPSTR) pBitmapInfo + (WORD) (pBitmapInfo -> biSize)) 


Bitmap Compression Formats 


Windows supports formats for compressing bitmaps that define their colors with 8 bits per 
pixel and with 4 bits per pixel. Compression reduces the disk and memory storage required 
for the bitmap. The following paragraphs describe these formats. 


When the biCompression field is set to BI_RLE8, the bitmap is compressed using a run- 
length encoding format for an 8-bit bitmap. This format may be compressed in either of 


two modes: 
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= Encoded 


= Absolute 


Both modes can occur anywhere throughout a single bitmap. 


Encoded mode consists of two bytes: the first byte specifies the number of consecutive 
pixels to be drawn using the color index contained in the second byte. In addition, the first 
byte of the pair can be set to zero to indicate an escape that denotes an end of line, end of 
bitmap, or a delta. The interpretation of the escape depends on the value of the second byte 
of the pair. The following list shows the meaning of the second byte: 


Second Byte 

Of Escape Meaning 

0 End of line. 

1 End of bitmap. 

2: Delta. The two bytes following the escape contain unsigned values in- 


dicating the horizontal and vertical offset of the next pixel from the 
current position. 


Absolute mode is signalled by the first byte set to zero and the second byte set to a value 
between 03H and FFH. In absolute mode, the second byte represents the number of bytes 
which follow, each of which contains the color index of a single pixel. When the second 
byte is set to 2 or less, the escape has the same meaning as in encoded mode. In absolute 
mode, each run must be aligned on a word boundary. 


The following example shows the hexadecimal values of an 8-bit compressed bitmap: 


03 04 95 06 BB G3 45 56 67 BH B2 78 BY G2 O5 G1 
O02 78 08 OB O9 1E OB D1 


This bitmap would expand as follows (two-digit values represent a color index for a single 
pixel): 


B4 G4 G4 

G6 @6 G6 B6 6 

45 56 67 

78 78 

move current position 5 right and 1 down 
78 78 

end of line 

JE CUE LEOLE. YE LE, Tete Te 

end of RLE bitmap 
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When the biCompression field is set to BI_RLE4, the bitmap is compressed using a run- 
length encoding format for a 4-bit bitmap, which also uses encoded and absolute modes. In 
encoded mode, the first byte of the pair contains the number of pixels to be drawn using 
the color indexes in the second byte. The second byte contains two color indexes, one in its 
high-order nibble (that is, its low-order four bits) and one in its low-order nibble. The first 
of the pixels is drawn using the color specified by the high-order nibble, the second is 
drawn using the color in the low-order nibble, the third is drawn with the color in the high- 
order nibble, and so on, until all the pixels specified by the first byte have been drawn. 


In absolute mode, the first byte contains zero, the second byte contains the number of color 
indexes that follow, and subsequent bytes contain color indexes in their high- and low- 
order nibbles, one color index for each pixel. In absolute mode, each run must be aligned 
on a word boundary. The end-of-line, end-of-bitmap, and delta escapes also apply to 
BI_RLE4. 


The following example shows the hexadecimal values of a 4-bit compressed bitmap: 


93 G4 95 G6 BB G6 45 56 67 OB B4 78 BB G2 M5 Ol 
G4 78 96 OO O9 1E BB O1 


This bitmap would expand as follows (single-digit values represent a color index for a 


single pixel): 

G46 

96069 

4°5 5: 6 6 7 

PO r 8 

move current position 5 right and 1 down 
PSP 3 

end of line 

fy SEO +E, ls Be Tea Belt 


end of RLE bitmap 


CLIENTCREATESTRUCT 
MDI Client Window Creation Structure 


The CLIENTCREATESTRUCT data structure contains information about the menu and 
first multiple document interface (MDI) child window of an MDI client window. An appli- 
cation passes a long pointer to this structure as the /pParam parameter of the Create Win- 
dow function when creating an MDI client window. 


typedef struct tagCLIENTCREATESTRUCT 
{ 
HMENU hWindowMenu; 
WORD idFirstChild; 
} CLIENTCREATESTRUCT ; 


The CLIENTCREATESTRUCT structure contains the following fields: 
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COLORREF 


COLORREF 


Color Specification 


Explict RGB 


Field Description 


hWindowMenu Is the menu handle of the application’s Window menu. An appli- 
cation can retrieve this handle from the MDI frame window’s 
menu using the GetSubMenu function. 


idFirstChild Is the child window ID of the first MDI child window created. 
Windows increments the ID for each additional MDI child 
window that the application creates, and reassigns identifiers 
when the application destroys a window to keep the range of 
identifiers continuous. These identifiers are used in WM_COM- 
MAND messages to the application’s MDI frame window when 
a child window is selected from the Window menu, and should 
not conflict with any other command identifiers. 


A COLORREF color value is a long integer that specifies a color. GDI functions that re- 
quire a color (such as CreatePen and FloodFill) accept a COLORREF value as a para- 
meter. Depending on how an application uses the COLORREF value, the value has three 
distinct forms. It may specify any of the following: 

m Explicit values for red, green, and blue (RGB) 

m= An index into a logical color palette 


= A palette-relative RGB value 


When specifying an explicit RGB value, the COLORREF value has the following hex- 
adecimal form: 


OxOObbggrr 


The low-order byte contains a value for the relative intensity of red; the second byte con- 
tains a value for green, and the third byte contains a value for blue. The high-order byte 
must be zero. The maximum value for a single byte is FF (hexadecimal). The following list 
illustrates the hexadecimal values that produce the indicated colors. 


Value Color 


Ox000000FF Pure red 
Ox0000FFO0 Pure green 


COLORREF 


Palette Index 
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Value Color 
0xO00FFO000 Pure blue 
0x00000000 Black 
OxOOFFFFFF White 
0x00808080 Medium gray 


The RGB macro accepts values for red, green, and blue, and returns an explicit RGB 
COLORREF value. 


When specifying an index into a logical color palette, the COLORREF value has the fol- 
lowing hexadecimal form: 


OxO100iiii 
The two low-order bytes consist of a 16-bit integer specifying an index into a logical 


palette. The third byte is not used and must be zero. The fourth (high-order) byte must be 
set to 1. 


For example, the hexadecimal value 0x01000000 specifies the color in the palette entry of 
index 0; 0x0100000C specifies the color in the entry of index 12, and so on. 


The PALETTEINDEX macro accepts an integer representing an index into a logical 
palette and returns a palette-index COLORREF value. 


Palette-Relative RGB 


Comments 


When specifying a palette-relative RGB value, the COLORREF value has the following 
hexadecimal form: 


Ox@2bbggrr 


As with an explicit RGB, the three low-order bytes contain values for red, green, and blue; 
the high-order byte must be set to 2. 


For output devices that support logical palettes, Windows matches a palette-relative RGB 
value to the nearest color in the logical palette of the device context, as though the applica- 
tion had specified an index to that palette entry. If an output device does not support a sys- 
tem palette, then Windows uses the palette-relative RGB as though it were an explict RGB 
COLORREF value. 


The PALETTERGB macro accepts values for red, green, and blue, and returns a palette- 
relative RGB COLORREF value. 


Before passing a palette-index or palette-relative RGB COLORREF value to a function 
that also requires a device-context parameter, an application that uses its own palette must 
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select its palette into the device context (by calling the SelectPalette function) and realize 
the palette (by calling RealizePalette). This ensures that the function will use the correct 
palette-entry color. For functions that create an object (such as CreatePen), the application 
must select and realize the palette before selecting the object for the device context. 


COMPAREITEMSTRUCT 


Owner-Draw Item-Sorting Information 


The COMPAREITEMSTRUCT structure supplies the identifiers and application-sup- 
plied data for two items in a sorted owner-draw combo box or list box. 


Whenever an application adds a new item to an owner-draw combo or list box created with 
the CBS_SORT or LBS_SORT style, Windows sends the owner a WM_COMPAREITEM 
message. The /Param parameter of the message contains a long pointer to a COMPARE- 
ITEMSTRUCT data structure. When the owner receives the message, the owner com- 
pares the two items and returns a value indicating which item sorts before the other. For 
more information, see the description of the WM_COMPAREITEM message in Chapter 6, 
“Messages Directory,” in Reference, Volume 1. 


typedef struct tagCOMPAREITEMSTRUCT { 
WORD CtlType; 
WORD Geld’: 
HWND hwndItem; 
WORD itemID1; 
DWORD itemDatal; 
WORD item1D2; 
DWORD itemData2; 
} COMPAREITEMSTRUCT; 


The COMPAREITEMSTRUCT structure has the following fields: 


Field Description 

CtlType Is ODT_LISTBOX (which specifies an owner-draw list box) or 
ODT_COMBOBOxX (which specifies an owner-draw combo box). 

CtlID Is the control ID for the list box or combo box. 

hwndItem Is the window handle of the control. 

itemID1 Is the index of the first item in the list box or combo box being com- 
pared. 

itemDatal Is application-supplied data for the first item being compared. This 


value was passed as the /Param parameter of the message that added 
the item to the combo or list box. 


COMSTAT 
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Field Description 
itemID2 Is the index of the second item in the list box or combo box being 
compared. 
itemData2 Is application-supplied data for the second item being compared. 


This value was passed as the /Param parameter of the message that 
added the item to the combo or list box. 


COMSTAT 


Communication-Device Status 


The COMSTAT structure contains information about a communications device. 


typedef struct tagCOMSTAT { 


BYTE fCtsHold: 
BYTE fDsrHold: 


BYTE fRlsdHold: 
BYTE fXoffHold: 
BYTE fXoffSent: 


BYTE fEofs Ts 

BYTE fTxim: 1; 

WORD cbInQue; 

WORD cbOutQue; 
} COMSTAT; 


lg 
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The COMSTAT structure has the following fields: 


Field 
fCtsHold: 1 


fDsrHold: 1 


fRisdHold: 1 


fXoffHold: 1 


fXoffSent: 1 


Description 


Specifies whether transmission is waiting for the clear-to-send 
(CTS) signal to be sent. 


Specifies whether transmission is waiting for the data-set-ready 
(DSR) signal to be sent. 


Specifies whether transmission is waiting for the receive-line- 
signal-detect (RLSD) signal to be sent. 


Specifies whether transmission is waiting as a result of the Xoff- 
Char character being received. 


Specifies whether transmission is waiting as a result of the Xoff- 
Char character being transmitted. Transmission halts when the 
XoffChar character is transmitted and used by systems that take 
the next character as XON, regardless of the actual character. 
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Field Description 
fEof: 1 Specifies whether the EofChar character has been received. 
fTxim: 1 Specifies whether a character is waiting to be transmitted. 
cbInQue Specifies the number of characters in the receive queue. 
cbOutQue Specifies the number of characters in the transmit queue. 
See Also The GetCommError function in Chapter 4, “Functions Directory,” in Reference, 
Volume I. 
CREATESTRUCT 


Window-Creation Structure 


The CREATESTRUCT structure defines the initialization parameters passed to an appli- 
cation’s window function. 


typedef struct tagCREATESTRUCT { 
LPSTR  lpCreateParams; 
HANDLE hInstance; 
HANDLE hMenu; 
HWND hwndParent; 


int cys 
int CX; 
int y3 
NG xs 


long style; 
LPSTR  JlpszName; 
LPSTR  JpszClasis:s 
long ExStyle; 

} CREATESTRUCT; 


The CREATESTRUCT structure has the following fields: 


Field Description 
IpCreateParams Points to data to be used for creating the window. 
hInstance Identifies the module-instance handle of the module that owns 


the new window. 


hMenu Identifies the menu to be used by the new window. 


DCB 


Field 


hwndParent 


cy 


cx 


y 


style 


IpszName 


IpszClass 


ExStyle 
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Description 


Identifies the window that owns the new window. This field is 
NULL if the new window is a top-level window. 


Specifies the height of the new window. 
Specifies the width of the new window. 


Specifies the y-coordinate of the upper-left corner of the new 
window. Coordinates are relative to the parent window if the 
new window is a child window. Otherwise, the coordinates are 
relative to the screen origin. 


Specifies the x-coordinate of the upper-left corner of the new 
window. Coordinates are relative to the parent window if the 
new window is a child window. Otherwise, the coordinates are 
relative to the screen origin. 


Specifies the new window’s style. 


Points to a null-terminated character string that specifies the new 
window’s name. 


Points to a null-terminated character string that specifies the new 
window’s class name. 


Specifies extended style for the new window. 


DCB 


Communications-Device Control Block 


The DCB structure defines the control setting for a serial communications device. 


typedef struct tagDCB { 


BYTE Id; 


WORD BaudRate; 
BYTE ByteSize; 
BYTE Parity; 
BYTE StopBits; 
WORD RlsTimeout; 
WORD CtsTimeout; 
WORD DsrTimeout; 


BYTE fBinary: 
BYTE fRtsDisable: 
BYTE fParity: 


ls 


BYTE fOutxCtsFlow: 1; 
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BYTE fOutxDsrFlow: 1; 
BYTE fDummy: 2; 
BYTE fDtrDisable: 1; 


BYTE FOutXxXs Ls 
BYTE flnxs ts 
BYTE fPeChar: 1; 
BYshE “ENUM 1s 
BYTE. FEhEVt: LT 
BYTE fDtrFlow: 1; 
BYTE fRtsFlow: 1; 
BYTE fDummy2: 1; 


char XonChar; 
char XoffChar; 
WORD XonLim; 
WORD XoffLim; 
char PeChar; 
char EofChar; 
char EvtChar; 
WORD TxDelay; 
} DCB; 


The DCB structure has the following fields: 


Field Description 


Id Specifies the communication device. This value is set by the 
device driver. If the most significant bit is set, then the DCB 
structure is for a parallel device. 


BaudRate Specifies the baud rate at which the communications device 
operates. 


ByteSize Specifies the number of bits in the characters transmitted and 
received. The ByteSize field can be any number from 4 to 8. 


Parity Specifies the parity scheme to be used. The Parity field can 
be any one of the following values: 


Value Meaning 
EVENPARITY ‘Even 
MARKPARITY Mark 
NOPARITY No parity 
ODDPARITY Odd 
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Field Description 
Value Meaning 
SPACEPARITY Space 
StopBits Specifies the number of stop bits to be used. The StopBits 
field can be any one of the following values: 
Value Meaning 
ONESTOPBIT 1 stop bit 
ONESSTOPBITS 1.5 stop bits 
TWOSTOPBITS 2 stop bits 
RlsTimeout Specifies the maximum amount of time (in milliseconds) the 


device should wait for the receive-line-signal-detect (RLSD) 
signal. (RLSD is also known as the carrier detect (CD) signal.) 


CtsTimeout Specifies the maximum amount of time (in milliseconds) the 
device should wait for the clear-to-send (CTS) signal. 

DsrTimeout Specifies the maximum amount of time (in milliseconds) the 
device should wait for the data-set-ready (DSR) signal. 

fBinary: 1 Specifies binary mode. In nonbinary mode, the EofChar 
character is recognized on input and remembered as the end of 
data. 

fRtsDisable: 1 Specifies whether or not the request-to-send (RTS) signal is 


disabled. If the fRtsDisable field is set, RTS is not used and re- 
mains low. If fRtsDisable is clear, RTS is sent when the 
device is opened and turned off when the device is closed. 


fParity: 1 Specifies whether parity checking is enabled. If the fParity 
field is set, parity checking is performed and errors are re- 
ported. 

fOutxCtsFlow: 1 Specifies that clear-to-send (CTS) signal is to be monitored 


for output flow control. If the fOutxCtsFlow field is set and 
CTS is turned off, output is suspended until CTS is again sent. 


fOutxDsrFlow: 1 Specifies that the data-set-ready (DSR) signal is to be moni- 
tored for output flow control. If the fOutxDsrFlow field is set 
and DSR is turned off, output is suspended until DSR is again 
sent. 


fDummy: 2 Reserved. 
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Field Description 


fDtrDisable: 1 Specifies whether the data-terminal-ready (DTR) signal is dis- 
abled. If the fDtrDisable field is set, DTR is not used and 
remains low. If fDtrDisable is clear, DTR is sent when the 
device is opened and turned off when the device is closed. 


fOutX: 1 Specifies that XON/XOFF flow control is used during trans- 
mission. If the fOutX field is set, transmission stops when the 
XoffChar character is received, and starts again when the 
XonChar character is received. 


fInX: 1 Specifies that XON/XOFF flow control is used during recep- 
tion. If the fInX field is set, the XonChar character is sent 
when the receive queue comes within XoffLim characters of 
being full, and the XonChar character is sent when the re- 
ceive queue comes within XonLim characters of being empty. 


fPeChar: 1 Specifies that characters received with parity errors are to be 
replaced with the character specified by the fPeChar field. 
The fParity field must be set for the replacement to occur. 


fNull: 1 Specifies that received null characters are to be discarded. 


fChEvt: 1 Specifies that reception of the EvtChar character is to be 
flagged as an event. 


fDtrFlow: 1 Specifies that the data-terminal-ready (DTR) signal is to be 
used for receive flow control. If the fDtrFlow field is set, 
DTR is turned off when the receive queue comes within Xof- 
fLim characters of being full, and sent when the receive queue 
comes within XonLim characters of being empty. 


fRtsFlow: 1 Specifies that the ready-to-send (RTS) signal is to be used for 
receive flow control. If the fRtsFlow field is set, RTS is 
turned off when the receive queue comes within XoffLim 
characters of being full, and sent when the receive queue 
comes within XonLim characters of being empty. 


fdummy2: 1 Reserved. 


XonChar Specifies the value of the XON character for both transmis- 
sion and reception. 


XoffChar Specifies the value of the XOFF character for both transmis- 
sion and reception. 


XonLim Specifies the minimum number of characters allowed in the re- 
ceive queue before the XON character is sent. 
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Field Description 


XoffLim Specifies the maximum number of characters allowed in the 
receive queue before the XOFF character is sent. The Xoff- 
Lim value is subtracted from the size of the receive queue (in 
bytes) to calculate the maximum number of characters al- 


lowed. 

PeChar Specifies the value of the character used to replace characters 
received with a parity error. 

EofChar Specifies the value of the character used to signal the end of 
data. 

EvtChar Specifies the value of the character used to signal an event. 

TxDelay Not currently used. 

See Also The BuildCommDCB, GetCommState, and SetCommState functions in Chapter 4, 


“Functions Directory,” in Reference, Volume 1. 


DELETEITEMSTRUCT 
Deleted Owner-Draw List-Box Item 


The DELETEITEMSTRUCT structure describes a deleted owner-draw list-box or 
combo-box item. When an item is removed from the list box or combo box, or when the 
list box or combo box is destroyed, Windows sends the WM_DELETEITEM message to 
the owner for each deleted item; the /Param parameter of the message contains a pointer to 
this structure. 


typedef struct tagDELETEITEMSTRUCT 
{ 


WORD CtlType 
WORD CED: 
WORD itemID; 
HWND hwndIitem; 
DWORD itemData; 


} DELETEITEMSTRUCT ; 


The DELETEITEMSTRUCT structure has the following fields: 
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Field 
CtlType 


CtlID 
itemID 


hwndItem 


itemData 


DEVMODE 


Description 


Is ODT_LISTBOX (which specifies an owner-draw list box) or 
ODT_COMBOBOxX (which specifies an owner-draw combo 
box). 


Is the control ID for the list box or combo box. 


Is the index of the item in the list box or combo box being re- 
moved. 


Is the window handle of the control. 


Contains the value passed to the control in the /Param parameter 
of the LB_INSERTSTRING, LB_ADDSTRING, CB_INSERT- 
STRING, or CB_ADDSTRING message when the item was 
added to the list box. 


Printer Driver Initialization Information 


The DEVMODE data structure contains information about the device initialization and en- 
vironment of a printer driver. An application passes this structure to the DeviceCapabili- 
ties and ExtDeviceMode functions. 


typedef struct _devicemode { 


char dmDeviceName[32]; 
WORD dmSpecVersion; 
WORD dmDriverVersion; 
WORD dmSize; 

WORD dmDriverExtra; 
DWORD dmFields; 

short dmOrientation; 
short dmPaperSize; 
short dmPaperLength; 
short  dmPaperWidth; 
short dmScale; 

short dmCopies; 

short dmDefaultSource; 
short dmPrintQuality; 
short dmColor; 

short  dmDuplex; 

BYTE dmDriverDataCdmDriverExtra]; 
} DEVMODE; 


The DEVMODE structure contains the following fields: 
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Field Description 


dmDeviceName Specifies the name of the device the driver supports; for 
example, “PCL/HP LaserJet” in the case of PCL/HP® 
LaserJet®. This string is unique among device drivers. 


dmSpecVersion Specifies the version number of the initialization data 
specification upon which the structure is based. The ver- 
sion number follows the Windows version number and is 
currently 0x300. 


dmDriver Version Specifies the printer driver version number assigned by the 
printer driver developer. 


dmSize Specifies the size in bytes of the DEVMODE structure 
except the dmDriverData (device-specific) field. If an 
application manipulates only the driver-independent por- 
tion of the data, it can use this field to determine the length 
of the structure without having to account for different ver- 
sions. 


dmDriverExtra Contains the size of the dmDriver Data field and is the 
length of the device-specific data in the DEVMODE 
structure. If an application does not use device-specific 
information, it should set this field to zero. 


dmFields Is a bitfield that specifies which of the remaining fields in 
the DEVMODE structure have been initialized. Bit 0 
(defined as DM_ORIENTATION) corresponds to 
dmOrientation; bit 1 (defined as DM_PAPERSIZE) 
specifies dmPaperSize, and so on. A printer driver sup- 
ports only those fields that are appropriate for the printer 


technology. 

dm Orientation Selects the orientation of the paper. It can be either 
DMORIENT_PORTRAIT (1) or DMORIENT_LAND- 
SCAPE (2). 

dmPaperSize Selects the size of the paper to print on. This field may be 


set to zero if the length and width of the paper are both set 
by the dmPaperLength and dmPaperWidth fields. Other- 
wise, the dmPaperSize field can be set to one of the 
following predefined values: 


Value Meaning 


DMPAPER_LETTER 814-by-11-inch paper 
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Field 


dmPaperLength 


dmPaper Width 


dmScale 


dmCopies 


dmDefaultSource 


DEVMODE 


Description 

Value Meaning 
DMPAPER_LEGAL 814-by-14-inch paper 
DMPAPER_A4 210-by-297-millimeter paper 


DMPAPER_CSHEET 17-by-22-inch paper 
DMPAPER_DSHEET 22-by-34-inch paper 
DMPAPER_ESHEET 34-by-44-inch paper 


DMPAPER_ENV_9 374-by-874-inch #9 envelope 
DMPAPER_ENV_10 414-by-9|4-inch #10 envelope 
DMPAPER_ENV_11 414-by-103%-inch #11 
envelope 
DMPAPER_ENV_12 43/4-by-11-inch #12 envelope 


DMPAPER_ENV_14 5-by-1114-inch #14 envelope 


Overrides the length of the paper specified by the 
dmPaperSize field, either for custom paper sizes or for 
devices such as dot-matrix printers which can print ona 
page of arbitrary length. These values, along with all other 
values which specify a physical length, are in tenths of a 
millimeter. 


Overrides the width of the paper specified by the 
dmPaperSize field. 


Scales the printed output. The apparent page size is scaled 
by a factor of dmScale/100 from the physical page size. A 
letter-size paper with a dmScale value of 50 would appear 
to be 17 by 22 inches, and output text and graphics would 

be correspondingly half their normal height and width. 


Selects the number of copies printed if the device supports 
multiple-page copies. 


Specifies the paper bin from which the paper is fed by de- 
fault. The application can override this selection by using 
the GETSETPAPERBINS escape. Possible bins include 
the following: 


DEVMODE 


Comments 
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Field 


dmPrintQuality 


dmColor 


dmDuplex 


dmDriverData[ ] 


Description 


DMBIN_DEFAULT 
DMBIN_UPPER 
DMBIN_LOWER 
DMBIN_MANUAL 
DMBIN_TRACTOR 
DMBIN_ENVELOPE 


There is also a range of values reserved for device-specific 
bins. The GETSETPAPERBINS and ENUMPAPERBINS 
escapes use these indexes to be consistent with initializa- 
tion information. 


Specifies the printer resolution. There are four predefined 
device-independent values: 


DMRES_ HIGH (-4) 
DMRES_MEDIUM (-3) 
DMRES_LOW (-2) 
DMRES_DRAFT (-1) 


If a positive value is given, it specifies the number of dots 
per inch (DPI) and is therefore device dependent. 


Switches between color and monochrome on color print- 
ers. Possible values are: 


= DMCOLOR_COLOR (1) 
us DMCOLOR_MONOCHROME (2). 


Selects duplex or double-sided printing for printers capable 
of duplex printing. Values for this field include: 


= DMDUP_SIMPLEX (1) 
= DMDUP_HORIZONTAL (2) 
= DMDUP_VERTICAL (3). 


Contains device-specific data defined by the device driver. 


Only drivers fully updated for Windows version 3.0 and which export the ExtDeviceMode 
function use the DEVMODE data structure. 
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DLGTEMPLATE 
Dialog Template 


The DLGTEMPLATE defines the contents of a dialog box. This structure is divided into 
three distinct parts: 


Part Description 

Header Data Contains a general description of the dialog box. 

Structure 

Font-Information Defines the font with which text is drawn in the dialog box. This 
Data Structure part is optional. 

List of Items Describes the parts that compose the dialog box. 


The CreateDialogIndirect, CreateDialogIndirectParam, DialogBoxIndirect, and Dial- 
ogBoxIndirectParam functions use this structure. 


Header Data Structure 
The DLGTEMPLATE header is shown here: 
typedef struct { 


long dtStyle; 
BYTE dtItemCount; 


int dtX; 
int dey. s 
int dtCx; 
int dteys 


char dtMenuName[]; 

char dtClassNameL[]; 

char dtCaptionTextl]; 
} DLG@TEMPLATE; 


The DLGTEMPLATE header has the following fields: 


Field Description 


dtStyle Specifies the style of the dialog box. This field may be any or 
all of these values: 
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Field Description 


Value Meaning 


DS_LOCALEDIT Specifies that text storage for 
edit controls will be allocated in 
the application’s local data seg- 
ment. This allows the use of the 
EM_GETHANDLE and 
EM_SETHANDLE messages. 
If this style is not specified, edit- 
control data is located in a 
separate global data block. 


DS_SYSMODAL Specifies a system-modal 
dialog box. 


DS_MODALFRAME Specifies a dialog box with a 
modal dialog-box border. This 
style can be combined with the 
WS_CAPTION and WS_SYS- 
MENU style flags to create a 
dialog box with a title bar and 
System menu. 


DS_ABSALIGN Indicates that dtX and dtY are 
relative to the screen origin, not 
to the owner of the dialog box. 


DS_SETFONT Specifies that a font other than 
the system font is to be used to 
draw text in the dialog box. If 
this flag is set, the FONTINFO 
data structure described in the 
following paragraphs must im- 
mediately follow the 
DLGTEMPLATE header. 


When Windows creates a 
dialog box with this attribute, 
Windows sends the WM_SET- 
FONT message to the 
dialog-box window prior to 
creating the controls. 
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Field 


dtItemCount 


dtX 


dtY 


dtCx 
dtCy 


dtMenuName[ ] 


dtClassName[ ] 


dtCaptionText[ ] 


DLGTEMPLATE 


Description 
Value Meaning 
DS_NOIDLEMSG Specifies that Windows will not 


send the WM_ENTERIDLE 
message to the owner of the 
dialog box while the dialog box 
is displayed. 


Specifies the number of items in the dialog box. A dialog box 
can contain up to 255 controls. 


Specifies the x-coordinate of the upper-left corner of the dialog 
box in units of 4 of the current dialog base width unit. The 
dialog base units are computed from the height and width of 
the current system font; the GetDialogBaseUnits function re- 
turns the current dialog base units in pixels. Unless 
DS_ABSALIGN is set in the dtStyle field, this value is rela- 
tive to the origin of the parent window’s client area. 


Specifies the y-coordinate of the upper-left corner of the dialog 
box in units of 1 of the current dialog base height unit. Unless 
DS_ABSALIGN is set in the dtStyle field, this value is rela- 
tive to the origin of the parent window’s client area. 


Specifies the width of the dialog box in units of /%4 of the 
dialog base width unit. 


Specifies the height of the dialog box in units of 1 of the 
dialog base height unit. 


Specifies a null-terminated string that specifies the name of the 
dialog box’s menu. If this field is NULL, the dialog-box 
window does not have a menu. 


Specifies a null-terminated string that supplies the name of the 
dialog box’s class. If dtClassName[ ] is zero, it creates a 
dialog box with the standard dialog-box style. If an application 
specifies a class name, it should provide a dialog procedure 
that processes each dialog-box message directly or calls the 
DefDlgProc function to process the message. Also, the applica- 
tion must register the class with the cbWndExtra field of the 
WNDCLASS data structure set to DLGWINDOWEXTRA. 


Specifies a null-terminated string that supplies the caption for 
the dialog box. 
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Font-Information Data Structure 


Item List 


The FONTINFO data structure contains information about the point size and face name of 
the font which Windows is to use to draw text in the dialog box. 


typedef struct{ 

short int PointSize; 

char szTypeFacel]; /* A null-terminated string */ 
} FONTINFO; 


The FONTINFO structure has the following fields: 


Field Description 

PointSize Specifies the size of the typeface in points. 

szTypeFace Specifies the name of the typeface; for example, “Courier”. 
Comments 


The font specified must have been previously loaded, either from WIN.INI or explicitly by 
calling the LoadFont function. 


The item list consists of one or more DLGITEMTEMPLATE data structures, one for 

each control in the dialog box. The first such structure immediately follows the FONT- 
INFO structure or the header at the first byte after the terminating null character in the 

szTypeFace field or the dtCaptionText[ ] field. The following shows the format of the 
DLGITEMTEMPLATE structure. 


typedef struct { 


int dtr ks 
ine Oe Ys 
int -dtilex; 
int. dtivey; 
Lac drs 


long dtilStyle; 
char dtilClass{]; 
char dtilTextl]; 
BYTE dtillInfo; 
PTR dtilData; 

} DLGITEMTEMPLATE 


The DLGITEMTEMPLATE data structure has the following fields: 
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dtilY 


dtilCX 


dtilCYy 


dtilID 
dtilStyle 
dtilClass[ ] 


dtilText[ ] 
dtilInfo 


dtilData 


Description 


Specifies the x-coordinate of the upper-left corner of the dialog-box 
item in units of 14 of the current dialog base width unit, relative to 
the origin of the dialog box. The dialog base units are computed from 
the height and width of the current system font. The GetDialog- 
BaseUnits function returns the current dialog base units in pixels. 


Specifies the y-coordinate of the upper-left corner of the dialog-box 
item in units of 1% of the current dialog base height unit. This value is 
relative to the origin of the dialog box. 


Specifies the width-extent of the dialog-box item in units of 4 of the 
current dialog base width unit. Dialog base units are computed from 
the height and width of the current system font. The GetDialog- 
BaseUnits function returns the current dialog base units. 


Specifies the height of the dialog-box item in units of 8 of the dialog 
base height unit. 


Specifies the dialog-box item identification number. 
Specifies the style of the dialog-box item. 


A null-terminated string that specifies the control’s class. It may be 
one of the following class names: 


STATIC 
LISTBOX 
SCROLLBAR 
COMBOBOX 


Specifies the text for the item; it is a null-terminated string. 


Specifies the number of bytes of additional data that follows this item 
description and precedes the next item description. 


Specifies additional data which the CreateWindow function receives 
through the IlpCreateParams field of the CREATESTRUCT data 
structure. This field is zero length if dtilInfo is zero. 
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Owner-Draw Control Drawing Information 


The DRAWITEMSTRUCT structure provides information the owner needs to determine 
how to paint an owner-draw control. The owner of the owner-draw control receives a 
pointer to this structure as the /Param parameter of the WM_DRAWITEM message. 


typedef struct tagDRAWITEMSTRUCT 

{ 
WORD CtlType; 
WORD CtlID; 
WORD itemID; 
WORD jtemAction; 
WORD itemState; 
HWND hwndItem; 
HDC hdc; 
RECT rcItem; 
DWORD itemData; 

} DRAWITEMSTRUCT; 


The DRAWITEMSTRUCT structure has the following fields: 


Field Description 

CtlType Is the control type. The values for control types are as follows: 
Value Meaning 
ODT_BUTTON Owner-draw button. 
ODT_COMBOBOX Owner-draw combo box. 
ODT_LISTBOX Owner-draw list box. 
ODT_MENU Owner-draw menu. 

CtlID Is the control ID for a combo box, list box or button. This field is 


not used for a menu. 


itemID Is the menu-item ID for a menu or the index of the item in a list 
box or combo box. For an empty list box or combo box, this field 
can be —1. This allows the application to draw only the focus 
rectangle at the coordinates specified by the reItem field even 
though there are no items in the control. This indicates to the user 
whether the list box or combo box has input focus. The setting of 
the bits in the itemAction field determines whether the rectangle is 
to be drawn as though the list box or combo box has input focus. 
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Field 


itemAction 


itemState 


hwndItem 


Description 


Defines the drawing action required. This will be one or more of 
the following bits: 


Value Description 

ODA_DRAWENTIRE This bit is set when the entire con- 
trol needs to be drawn. 

ODA_FOCUS This bit is set when the control 


gains or loses input focus. The item- 
State field should be checked to 
determine whether the control has 
focus. 


ODA_SELECT This bit is set when only the selec- 
tion status has changed. The 
itemState field should be checked 
to determine the new selection state. 


Specifies the visual state of the item after the current drawing ac- 
tion takes place. That is, if a menu item is to be grayed, the state 
flag ODS_GRAYED will be set. The state flags are: 


Value Description 

ODS_CHECKED This bit is set if the menu item is to 
be checked. This bit is used only in 
a menu. 

ODS_DISABLED This bit is set if the item is to be 
drawn as disabled. 

ODS_FOCUS This bit is set if the item has input 
focus. 

ODS_GRAYED This bit is set if the item is to be 
grayed. This bit is used only ina 
menu. 

ODS_SELECTED This bit is set if the item’s status is 
selected. 


For combo boxes, list boxes and buttons, this field specifies the 
window handle of the control; for menus, it contains the handle of 
the menu (HMENU) containing the item. 
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Field Description 


hDC Identifies a device context; this device context must be used when 
performing drawing operations on the control. 


rcItem Is a rectangle in the device context specified by the hDC field that 
defines the boundaries of the control to be drawn. Windows auto- 
matically clips anything the owner draws in the device context for 
combo boxes, list boxes, and buttons, but does not clip menu items. 
When drawing menu items, the owner must ensure that the owner 
does not draw outside the boundaries of the rectangle defined by 
the reItem field. 


itemData For a combo box or list box, this field contains the value that was 
passed to the list box in the /Param parameter of one of the the fol- 
lowing messages: 


a CB_ADDSTRING 
a CB_INSERTSTRING 
a LB_ADDSTRING 
a LB_INSERTSTRING 


For a menu, this field contains the DWORD value passed as the 
IpNewlItem parameter of the InsertMenu which inserted the menu 
item. Its contents are undefined for buttons. 


HANDLETABLE 
Window-Handle Table 


The HANDLETABLE structure is an array of handles, each of which identifies a GDI ob- 
ject. 


HANDLE objectHandle[1] 


The HANDLETABLE structure has the following field: 


Field Description 


objectHandle[1] Identifies an array of handles. 
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LOGBRUSH 


Logical-Brush Attribute Information 


The LOGBRUSH structure defines the style, color, and pattern of a physical brush to be 
created by using the CreateBrushIndirect function. 


typedef struct tagLOGBRUSH [{ 
WORD lbStyle; 
COLORREF 1bColor; 
short int lbHatch; 

} LOGBRUSH; 


The LOGBRUSH structure has the following fields: 


Field Description 
IbStyle Specifies the brush style. The IbStyle field can be any one of the following 
styles: 
Style Meaning 
BS_DIBPATTERN Specifies a pattern brush defined by a device-in- 
dependent bitmap (DIB) specification. 
BS_HATCHED Specifies a hatched brush. 
BS_HOLLOW Specifies a hollow brush. 
BS_PATTERN Specifies a pattern brush defined by a memory 
bitmap. 
BS_SOLID Specifies a solid brush. 


IbColor Specifies the color in which the brush is to be drawn. If IbStyle is 
BS_HOLLOW or BS_PATTERN, IbColor is ignored. 


If IpStyle is BS_DIBPATTERN, the low-order word of IbColor specifies 
whether the bmiColors fields of the BITMAPINFO data structure con- 
tain explicit RGB values or indexes into the currently realized logical 
palette. The IbColor field must be one of the following values: 


Value Meaning 


DIB_PAL_COLORS The color table consists of an array of 16-bit in- 
dexes into the currently realized logical palette. 


DIB_RGB_COLORS The color table contains literal RGB values. 
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Field Description 


IbHatch Specifies a hatch style. The meaning depends on the brush style. 


If lbStyle is BS_DIBPATTERN, the lbHatch field contains a handle to a 
packed DIB. To obtain this handle, an application calls the GlobalAlloc 
function to allocate a block of global memory and then fills the memory 
with the packed DIB. A packed DIB consists of a BITMAPINFO data 
structure immediately followed by the array of bytes which define the pix- 
els of the bitmap. 


If lbStyle is BS_HATCHED, the lbHatch field specifies the orientation of 
the lines used to create the hatch. It can be any one of the following 


values: 

Value Meaning 

HS_BDIAGONAL 45-degree upward hatch (left to right) 
HS_CROSS Horizontal and vertical crosshatch 
HS_DIAGCROSS 45-degree crosshatch 
HS_FDIAGONAL 45-degree downward hatch (left to right) 
HS_HORIZONTAL Horizontal hatch 

HS_VERTICAL Vertical hatch 


If IbStyle is BS_PATTERN, IbHatch must be a handle to the bitmap that 
defines the pattern. 


If IbStyle is BS_SOLID or BS_HOLLOW, IbHatch is ignored. 


See Also The CreateBrushIndirect function in Chapter 4, “Functions Directory,” in Reference, 
Volume I. 


LOGFONT 


Logical-Font Descriptor 


The LOGFONT structure defines the attributes of a font, a drawing object used to write 
text on a display surface. 
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typedef struct tagLOGFONT { 
short int lfHeight; 
short int 1fWidth; 
short int 1fEscapement; 
short int 1fOrientation; 
short int 1fWeight; 


BYTE lfItalic; 

BYTE 1fUnderline; 

BYTE 1fStrikeOut; 

BYTE 1fCharSet; 

BYTE 1fOutPrecision; 

BYTE 1fClipPrecision; 

BYTE 1fQuality; 

BYTE 1fPitchAndFamily; 

BYTE 1fFaceNameLLF_FACESIZE]; 
} LOGFONT; 


The LOGFONT structure has the following fields: 


Field Description 


IfHeight Specifies the average height of the font (in user units). The 
height of a font can be specified in the following three ways. If 
the IfHeight field is greater than zero, it is transformed into 
device units and matched against the cell height of the availa- 
ble fonts. If IfHeight is zero, a reasonable default size is used. 
If IfHleight is less than zero, it is transformed into device units 
and the absolute value is matched against the character height 
of the available fonts. 


IfWidth Specifies the average width of characters in the font (in device 
units). If the IfWidth field is zero, the aspect ratio of the 
device is matched against the digitization aspect ratio of the 
available fonts for the closest match by absolute value of the 
difference. 


IfEscapement Specifies the angle (in tenths of degrees) between the escape- 
ment vector and the x-axis of the display surface. The 
escapement vector is the line through the origins of the first 
and last characters on a line. The angle is measured counter- 
clockwise from the x-axis. 


IfOrientation Specifies the angle (in tenths of degrees) between the baseline 
of a character and the x-axis. The angle is measured counter- 
clockwise from the x-axis. 


LOGFONT 


Field 
IfWeight 


Ifltalic 
IfUnderline 
IfStrikeOut 
IfCharSet 


IfOutPrecision 


IfClipPrecision 


IfQuality 
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Description 


Specifies the font weight (in inked pixels per 1000). Although 
the IfWeight field can be any integer value from 0 to 1000, the 
common values are as follows: 


400 Normal 
700 ~=Bold 


These values are approximate; the actual appearance depends 
on the font face. If IfWeight is zero, a default weight is used. 


Specifies an italic font if set to nonzero. 
Specifies an underlined font if set to nonzero. 
Specifies a strikeout font if set to nonzero. 


Specifies the font’s character set. The three values are 
predefined: 


ANSI_CHARSET 
OEM_CHARSET 
SYMBOL_CHARSET 


The OEM character set is system-dependent. 


Fonts with other character sets may exist in the system. If an 
application uses a font with an unknown character set, it 
should not attempt to translate or interpret strings that are to be 
rendered with that font. Instead, the strings should be passed 
directly to the output device driver. 


Specifies the font’s output precision, which defines how 
closely the output must match the requested font’s height, 
width, character orientation, escapement, and pitch. The de- 
fault setting is OUT.DEFAULT_PRECIS. 


Specifies the font’s clipping precision, which defines how to 
clip characters that are partially outside the clipping region. 
The default setting is CLIP_DEFAULT_PRECIS. 


Specifies the font’s output quality, which defines how carefully 
GDI must attempt to match the logical-font attributes to those 
of an actual physical font. It can be any one of the following 
values: 
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Field 


IfPitchAndFamily 


Description 


Value 


DEFAULT_QUALITY 


DRAFT_QUALITY 


PROOF_QUALITY 


Meaning 


Appearance of the font does not 
matter. 


Appearance of the font is less 
important than when 
PROOF_QUALITY is used. 
For GDI fonts, scaling is 
enabled, which means that 
more font sizes are available, 
but the quality may be lower. 
Bold, italic, underline, and 
strikeout fonts are synthesized 
if necessary. 


Character quality of the font is 
more important than exact 
matching of the logical-font at- 
tributes. For GDI fonts, scaling 
is disabled and the font closest 
in size is chosen. Although the 
chosen font size may not be 
mapped exactly when 
PROOF_QUALITY is used, the 
quality of the font is high and 
there is no distortion of appear- 
ance. Bold, italic, underline, 
and strikeout fonts are synthe- 
sized if necessary. 


Specifies the font pitch and family. The two low-order bits 
specify the pitch of the font and can be any one of the follow- 


ing values: 


DEFAULT_PITCH 
FIXED_PITCH 
VARIABLE_PITCH 


The four high-order bits of the field specify the font family and 
can be any one of the following values: 


LOGFONT 


Field 


lffaceName 
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Description 


FF_DECORATIVE 
FF_DONTCARE 
FF_MODERN 
FF_ROMAN 
FF_SCRIPT 
FF_SWISS 


The proper value can be obtained by using the Boolean OR 
operator to join one pitch constant with one family constant. 


Font families describe the look of a font in a general way. They 
are intended for specifying fonts when the exact typeface 
desired is not available. The values for font families are as fol- 
lows: 


Value Meaning 
FF_DECORATIVE 
FF_DONTCARE 
FF_MODERN 


Novelty fonts. 
Don’t care or don’t know. 


Fonts with constant stroke 
width (fixed-pitch), with or 
without serifs. Fixed-pitch fonts 
are usually modern. 


FF_ROMAN Fonts with variable stroke 
width (proportionally spaced) 


and with serifs. 


FF_SCRIPT Fonts designed to look like 


handwriting. 


FF_SWISS Fonts with variable stroke 
width (proportionally spaced) 
and without serifs. 


Specifies the font’s typeface. It must be a null-terminated 
character string. If lfFaceName is NULL, GDI uses a default 
typeface. 
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See Also The CreateFontIndirect function in Chapter 4, “Functions Directory,” in Reference, 
Volume I. 


LOGPALETTE 


Logical Color Palette Information 
The LOGPALETTE data structure defines a logical color palette. 


typedef struct 
{ 
WORD palVersion; 
WORD palNumEntries; 
PALETTEENTRY palPalEntry[]; 
} LOGPALETTE; 


The LOGPALETTE structure has the following fields: 


Field Description 

palVersion Specifies the Windows version number for the structure (cur- 
rently 0x300). 

palNumEntries Specifies the number of palette color entries. 

palPalEntry [ ] Specifies an array of PALETTEENTRY data structures that 


define the color and usage of each entry in the logical palette. 


Comments The colors in the palette entry table should appear in order of importance. This is because 
entries earlier in the logical palette are most likely to be placed in the system palette. 


This data structure is passed as a parameter to the CreatePalette function. 


LOGPEN 


Logical-Pen Attribute Information 


The LOGPEN structure defines the style, width, and color of a pen, a drawing object used 
to draw lines and borders. The CreatePenIndirect function uses the LOGPEN structure. 


typedef struct tagLOGPEN { 
WORD lopnStyle; 
POINT lopnWidth; 
COLORREF JlopnColor; 

} LOGPEN; 
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The LOGPEN structure has the following fields: 


Field Description 

lopnStyle Specifies the pen type, which can be any one of 
the following values: 
Constant Name Value Result 
PS_SOLID 0 es 
PS_DASH 1 --- 
PS_DOT 2 
PS_DASHDOT 3 —.- 
PS_DASHDOTDOT 4 ee 
PS_NULL =) 
PS_INSIDEFRAME 6 


If the width of the pen is greater than 1 and the pen style is 
PS_INSIDEFRAME, the line is drawn inside the frame of all 
primitives except polygons and polylines; the pen is drawn 
with a logical (dithered) color if the pen color does not match 
an available RGB value. The PS_INSIDEFRAME style is 
identical to PS_SOLID if the pen width is less than or equal 
to 1. 


lopnWidth Specifies the pen width (in logical units). If the 
lopnWidth field is zero, the. pen is one pixel 
wide on raster devices. 


lopnColor Specifies the pen color. 
Comments The y value in the POINT structure for lopnWidth is not used. 
See Also The CreatePenIndirect function in Chapter 4, “Functions Directory,” in Reference, 


Volume I. 
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MDICREATESTRUCT 
MDI Child Window Creation Structure 


The MDICREATESTRUCT data structure contains information about the class, title, 
owner, location, and size of a multiple document interface (MDI) child window. 


typedef struct tagMDICREATESTRUCT 
{ 
LPSTR szClass; 
LESTER | JSziitkers 
HANDLE hOwner; 


int xe 

int y3 

int oxs 
int cy; 
LONG style; 


LONG 1Param; 
} MDICREATESTRUCT; 


The MDICREATESTRUCT structure contains the following fields: 


Field Description 

szClass Contains a long pointer to the application-defined class of the 
MDI child window. 

szTitle Contains a long pointer to the window title of the MDI child 
window. 

hOwner Is the instance handle of the application creating the MDI child 
window. 

x Specifies the initial position of the left side of the MDI child 


window. If set to CW_USEDEFAULT, the MDI child window 
is assigned a default horizontal position. 


y Specifies the initial position of the top edge of the MDI child 
window. If set to CW_USEDEFAULT, the MDI child window 
is assigned a default vertical position. 


cx Specifies the initial width of the MDI child window. If set to 
CW_USEDEFAULT, the MDI child window is assigned a 
default width. 

cy Specifies the initial height of the MDI child window. If set to 


CW_USEDEFAULT, the MDI child window is assigned a 
default height. 
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Comments 


Field Description 


style Specifies additional styles for the MDI child window. The style 
field may be set to one or more of the following values: 


Value Meaning 


WS_MINIMIZE The MDI child window is created in a 
minimized state. 


WS_MAXIMIZE The MDI child window is created ina 
maximized state. 


WS_HSCROLL The MDI child window is created with a 
horizontal scroll bar. 


WS_VSCROLL The MDI child window is created with a 
vertical scroll bar. 


lParam Is an application-defined 32-bit value. 


When the MDI child window is created, Windows sends the WM_CREATE message to 
the window. The /Param parameter of the WM_CREATE message contains a pointer to a 
CREATESTRUCT data structure. The IpCreateParams field of the CREATESTRUCT 
structure contains a pointer to the MDICREATESTRUCT data structure passed with the 
WM_MDICREATE message that created the MDI child window. 


MEASUREITEMSTRUCT 


Owner-Draw Control Dimensions 


The MEASUREITEMSTRUCT data structure informs Windows of the dimensions of an 
owner-draw control. This allows Windows to process user interaction with the control cor- 
rectly..The owner of an owner-draw control receives a pointer to this structure as the 
[Param parameter of an WM_MEASUREITEM message. The owner-draw control sends 
this message to its owner window when the control is created; the owner then fills in the 
appropriate fields in the structure for the control and returns. This structure is common to 
all owner-draw controls. 


The MEASUREITEMSTRUCT structure has the following format: 


typedef struct tagMEASUREITEMSTRUCT 
{ 
WORD CtlType; 
WORD Ctl IDs 
WORD itemID; 
WORD itemWidth; 
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WORD itemHeight; 
DWORD 
} MEASUREITEMSTRUCT ; 


The MEASUREITEMSTRUCT structure contains the following fields: 


Field 
CtlType 


CtlID 


itemID 


item Width 


itemHeight 


itemData 


Description 


Is the control type. The values for control types are as follows: 


Value Meaning 
ODT_BUTTON Owner-draw button. 
ODT_COMBOBOX Owner-draw combo box. 
ODT_LISTBOX Owner-draw list box. 
ODT_MENU Owner-draw menu. 


Is the control ID for a combo box, list box, or button. This field 
is not used for a menu. 


Is the menu-item ID for a menu or the list-box item ID for a vari- 
able-height combo box or list box. This field is not used for a 
fixed-height combo box or list box, or for a button. 


Specifies the width of a menu item. The owner of the owner- 
draw menu item must fill this field before returning from the 
message. 


Specifies the height of an individual item in a list box or a menu. 
Before returning from the message, the owner of the owner- 
draw combo box, list box, or menu item must fill out this field. 


Contains the value that was passed to the combo box or list box 
in the /Param parameter of one of the following messages: 


a CB_ADDSTRING 
a CB_INSERTSTRING 
a LB_ADDSTRING 
u LB_INSERTSTRING 


Contains the DWORD value passed as the /pNew/tem parameter 
of the AppendMenu, InsertMenu, or ModifyMenu function 
that added or modified the menu item. Its contents are undefined 
for buttons. 
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Comments Failure to fill out the proper fields in the MEASUREITEM structure will cause improper 
operation of the control. 


MENUITEMTEMPLATE 


Menu-ltemTemplate 


A complete menu template consists of a header and one or more menu-item lists. The fol- 
lowing shows the structure of the menu-template header: 


typedef struct { 
WORD versionNumber ; 
WORD offset; 

} MENUITEMTEMPLATEHEADER; 


The menu-template header contains the following fields: 


Field Description 
versionNumber Specifies the version number. Should be zero. 
offset Specifies the offset from the header in bytes where the 


menu-item list begins. 


One or more MENUITEMTEMPLATE structures are combined to form the menu-item 
list. 


typedef struct { 
WORD mtOption; 
WORD mtID; 
LPSTR mtString; 
} MENUITEMTEMPLATE; 


The MENUITEMTEMPLATE structure has the following fields: 


Field Description 


mtOption Specifies a mask of one or more predefined menu options that 


specify the appearance of the menu item. The menu options are as 
follows: 
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MENUITEMTEMPLATE 


See also 


Field Description 


Value 

MF_CHECKED 
MF_END 

MF_GRAYED 
MF_HELP 
MF_MENUBARBREAK 


MF_MENUBREAK 
MF_OWNERDRAW 


Meaning 
Item has a checkmark next to it. 


Item must be specified for the last 
item in a pop-up menu or a static 
menu. 


Item is initially inactive and drawn 
with a gray effect. 


Item has a vertical separator to its 
left. 


Item is placed in a new column. The 
old and new columns are separated 
by a bar. 


Item is placed in a new column. 


The owner of the menu is re- 
sponsible for drawing all visual 
aspects of the menu item, including 
highlighted, checked and inactive 
states. This option is not valid for a 
top-level menu item. 


MF_POPUP Item displays a sublist of menu 
items when selected. 
mtID Specifies an identification code for a nonpop-up menu item. The 


MENUITEMTEMPLATE data structure for a pop-up menu item 
does not contain the mtID field. 


mtString Points to a null-terminated character string that specifies the name 


of the menu item. 


The LoadMenulIndirect function in Chapter 4, “Functions Directory,” in Reference, 


Volume 1. 
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METAFILEPICT 


Metafile Picture Structure 


The METAFILEPICT structure defines the metafile picture format used for exchanging 
metafile data through the clipboard. 


typedef struct tagMETAFILEPICT { 


int mm ; 
int KEKE V-Exts 
HANDLE hMF; 

} METAFILEPICT; 


The METAFILEPICT structure has the following fields: 


Field Description 
mm Specifies the mapping mode in which the picture is drawn. 
xExt Specifies the size of the metafile picture for all modes except the 


MM_ISOTROPIC and MM_ANISOTROPIC modes. The x-extent speci- 
fies the width of the rectangle within which the picture is drawn. The 
coordinates are in units that correspond to the mapping mode. 


yExt Specifies the size of the metafile picture for all modes except the 
MM_ISOTROPIC and MM_ANISOTROPIC modes. The y-extent speci- 
fies the height of the rectangle within which the picture is drawn. The 
coordinates are in units that correspond to the mapping mode. 


For MM_ISOTROPIC and MM_ANISOTROPIC modes, which can be 
scaled, the xExt and yExt fields contain an optional suggested size in 
MM_HIMETRIC units. For MM_ANISOTROPIC pictures, xExt and 
yExt can be zero when no suggested size is supplied. For 
MM_ISOTROPIC pictures, an aspect ratio must be supplied even when 
no suggested size is given. (If a suggested size is given, the aspect ratio 
is implied by the size.) To give an aspect ratio without implying a sug- 
gested size, set xExt and yExt to negative values whose ratio is the 
appropriate aspect ratio. The magnitude of the negative xExt and yExt 
values will be ignored; only the ratio will be used. 


hMF Identifies a memory metafile. 
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MSG 


Message Data Structure 
The MSG structure contains information from the Windows application queue. 


typedef struct tagMSG { 
HWND hwnd; 
WORD message; 
WORD wParam; 
LONG 1Param; 


DWORD time; 
POINT pt; 
} MSG; 


The MSG structure has the following fields: 


Field Description 

hwnd Identifies the window that receives the message. 

message Specifies the message number. 

wParam Specifies additional information about the message. The exact meaning 
depends on the message value. 

|Param Specifies additional information about the message. The exact meaning 
depends on the message value. 

time Specifies the time at which the message was posted. 

pt Specifies the position of the cursor (in screen coordinates) when the 


message was posted. 


MULTIKEYHELP 
Windows Help Key Word Table Structure 


The MULTIKEYHELP structure specifies a key-word table and an associated key word 
to be used by the Windows Help application. 


typedef struct tagMULTIKEYHELP { 
WORD mkSize; 
BYTE mkKeylist; 
BYTE szKeyphrasel[]; 

} MULTIKEYHELP; 


The MULTIKEYHELP data structure contains the following fields: 


OFSTRUCT 


OFSTRUCT 


Open-File Structure 
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Field Description 
mkSize Specifies the length of the MULTIKEYHELP structure (in 
bytes). 
mkKeylist Contains a single character that identifies the key-word table to 
be searched. 
szKeyphrase[ ] Contains a null-terminated text string that specifies the key word 


to be located in the key-word table. 


The OFSTRUCT structure contains file information which results from opening that file. 


typedef struct tagOFSTRUCT { 
BYTE cBytes; 
BYTE fFixedDisk; 
WORD nErrCode; 
BYTE reserved[4]; 
BYTE szPathNamel120]; 
} OFSTRUCT; 


The OFSTRUCT structure has the following fields: 


Field Description 

cBytes Specifies the length of the OFSTRUCT structure (in bytes). 

fFixedDisk Specifies whether the file is on a fixed disk. The fFixedDisk 
field is nonzero if the file is on a fixed disk. 

nErrCode Specifies the DOS error code if the OpenFile function returns 
—| (that is, OpenFile failed). 

reserved[4] Reserved field. Four bytes reserved for future use. 


szPathName[120] Specifies 120 bytes that contain the pathname of the file. This 


string consists of characters from the OEM character set. 
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PAINTSTRUCT 


Windows Paint Information 


The PAINTSTRUCT structure contains information for an application. This information 
can be used to paint the client area of a window owned by that application. 


typedef struct tagPAINTSTRUCT { 
HDC hdc; 
BOOL fErase; 
RECT rcPaint; 
BOOL fRestore; 
BOOL fIncUpdate; 
BYTE rgbReserved[16]; 
} PAINTSTRUCT; 


The PAINTSTRUCT structure has the following fields: 


Field Description 

hde Identifies the display context to be used for painting. 

fErase Specifies whether the background has been redrawn. It has been 
redrawn if nonzero. 

rcePaint Specifies the upper-left and lower-right corners of the rectangle 
in which the painting is requested. 

fRestore Reserved field. It is used internally by Windows. 

fIncUpdate Reserved field. It is used internally by Windows. 


rgbReserved[16] Reserved field. A reserved block of memory used internally by 
Windows. 


PALETTEENTRY 
Logical Palette Color Entry 


The PALETTEENTRY data structure specifies the color and usage of an entry in a logi- 
cal color palette. A logical palette is defined by a LOGPALETTE data structure. 


typedef struct 
{ 
BYTE peRed; 
BYTE peGreen; 
BYTE peBlue; 
BYTE peFlags; 
} PALETTEENTRY; 
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The PALETTEENTRY structure contains the following fields: 


Field Description 

peRed Specifies the intensity of red for the palette entry color. 

peGreen Specifies the intensity of green for the palette entry color. 

peBlue Specifies the intensity of blue for the palette entry color. 

peFlags Specifies how the palette entry is to be used. The peF lags field may be 
set to NULL or one of these values: 
Flag Meaning 
PC_EXPLICIT Specifies that the low-order word of the 


logical palette entry designates a hard- 

ware palette index. This flag allows the 
application to show the contents of the 

display-device palette. 


PC_NOCOLLAPSE Specifies that the color will be placed in 
an unused entry in the system palette in- 
stead of being matched to an existing 
color in the system palette. If there are no 
unused entries in the system palette, the 
color is matched normally. Once this 
color is in the system palette, colors in 
other logical palettes can be matched to 
this color. 


PC_RESERVED Specifies that the logical palette entry 
will be used for palette animation; this 
prevents other windows from matching 
colors to this palette entry since the color 
will frequently change. If an unused sys- 
tem-palette entry is available, this color 
is placed in that entry. Otherwise, the 
color will not be available for animation. 


POINT 


Point Data Structure 


The POINT structure defines the x- and y-coordinates of a point. 


7-57 


RECT 


SES BT SE A 


See Also 


typedef struct tagPOINT ( 
int x; 
Abe ¥'s 

} POINT; 


The POINT structure has the following fields: 


Field Description 
x Specifies the x-coordinate of a point. 
y Specifies the y-coordinate of a point. 


The ChildWindowFromPoint, PtInRect, and WindowFromPoint functions in Chapter 
4, “Functions Directory,” in Reference, Volume I. 


RECT 


Rectangle Data Structure 


Commenis 


The RECT structure defines the coordinates of the upper-left and lower-right corners of a 
rectangle. 


typedef struct tagRECT { 
int left; 
int top; 
int right; 
int bottom; 
JUREGTs 


The RECT structure has the following fields: 


Field Description 

left Specifies the x-coordinate of the upper-left comer of a rectangle. 
top Specifies the y-coordinate of the upper-left corner of a rectangle. 
right Specifies the x-coordinate of the lower-right corner of a rectangle. 
bottom Specifies the y-coordinate of the lower-right corner of a rectangle. 


The width of the rectangle defined by the RECT structure must not exceed 32,768 units. 
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RGBQUAD [3.0] 
RGB Color Structure 


The RGBQUAD data structure describes a color consisting of relative intensities of red, 
green, and blue. The bmiColors field of the BITMAPINFO data structure consists of an 
array of RGBQUAD data structures. 


typedef struct tagRGBQUAD { 
BYTE rgbBlue; 
BYTE rgbGreen; 
BYTE rgbRed; 
BYTE rgbReserved; 
} RG@BQUAD; 


The RGBQUAD structure contains the following fields: 


Field Description 

rgbBlue Specifies the intensity of blue in the color. 
rgbGreen Specifies the intensity of green in the color. 
rgbRed Specifies the intensity of red in the color. 
rgbReserved Is not used and must be set to zero. 


RGBTRIPLE 
RGB Color Structure 


The RGBTRIPLE data structure describes a color consisting of relative intensities of red, 


green, and blue. The bmciColors field of the BITMAPCOREINFO data structure con- 
sists of an array of RGBTRIPLE data structures. 


typedef struct tagRGBTRIPLE { 
BYTE rgbtBlue; 
BYTE rgbtGreen; 
BYTE rgbtRed; 

} RGBTRIPLE; 


The RGBTRIPLE structure contains the following fields: 
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Field Description 
rgbtBlue Specifies the intensity of blue in the color. 
rgbtGreen Specifies the intensity of green in the color. 
rgbtRed Specifies the intensity of red in the color. 
TEXTMETRIC 


Basic Font Metrics 


The TEXTMETRIC structure contains basic information about a physical font. All sizes 
are given in logical units; that is, they depend on the current mapping mode of the display 
context. 


typedef struct tagTEXTMETRIC { 
short int tmHeight; 
short int tmAscent; 
short int tmDescent; 
short int tmInternalLeading; 
short int tmExternalLeading; 
short int tmAveCharWidth; 
short int tmMaxCharWidth; 
short int tmWeight; 


BYTE tmItalic; 

BYTE tmUnderlined; 
BYTE tmStruckOut; 

BYTE tmFirstChar; 

BYTE tmLastChar; 

BYTE tmDefaultChar; 
BYTE tmBreakChar; 

BYTE tmPitchAndFamily; 
BYTE tmCharSet; 


short int tmOverhang; 

short int tmDigitizedAspectx; 

short int tmDigitizedAspectY; 
} TEXTMETRIC; 


The TEXTMETRIC structure has the following fields: 


Field Description 
tmHeight Specifies the height (ascent + descent) of characters. 
tmAscent Specifies the ascent (units above the baseline) of 


characters. 


TEXTMETRIC 


Field 


tmDescent 


tmInternalLeading 


tmExternalLeading 


tmAveCharWidth 


tmMaxChar Width 
tmWeight 

tmltalic 
tmUnderlined 
tmStruckOut 
tmFirstChar 


tmLastChar 
tmDefaultChar 
tmBreakChar 


tmPitchAndFamily 
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Description 


Specifies the descent (units below the baseline) of 
characters. 


Specifies the amount of leading (space) inside the 
bounds set by the tmHeight field. Accent marks and 
other foreign characters may occur in this area. The de- 
signer may set this field to zero. 


Specifies the amount of extra leading (space) that the 
application adds between rows. Since this area is outside 
the font, it contains no marks and will not be altered by 
text output calls in either OPAQUE or TRANSPARENT 
mode. The designer may set this field to zero. 


Specifies the average width of characters in the font 
(loosely defined as the width of the letter x). This value 
does not include overhang required for bold or italic 
characters. 


Specifies the width of the widest character in the font. 
Specifies the weight of the font. 

Specifies an italic font if it is nonzero. 

Specifies an underlined font if it is nonzero. 

Specifies a struckout font if it is nonzero. 


Specifies the value of the first character defined in the 
font. 


Specifies the value of the last character defined in the 
font. 


Specifies the value of the character that will be substi- 
tuted for characters that are not in the font. 


Specifies the value of the character that will be used to 
define word breaks for text justification. 


Specifies the pitch and family of the selected font. The 
low-order bit specifies the pitch of the font. If it is 1, the 
font is variable pitch. If it is 0, the font is fixed pitch. 
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TEXTMETRIC 


See Also 


Field Description 


The four high-order bits designate the font family. The 
tmPitchAndFamily field can be combined with the hex- 
adecimal value OxFO by using the bitwise AND operator, 
and then be compared with the font family names for an 
identical match. For a description of the font families, 
see the LOGFONT structure, earlier in this chapter. 


tmCharSet Specifies the character set of the font. 


tmOverhang Specifies the per-string extra width that may be added to 
some synthesized fonts. When synthesizing some at- 
tributes, such as bold or italic, GDI or a device may have 
to add width to a string on both a per-character and per- 
string basis. For example, GDI makes a string bold by 
expanding the intracharacter spacing and overstriking by 
an offset value; it italicizes a font by skewing the string. 
In either case, there is an overhang past the basic string. 
For bold strings, the overhang is the distance by which 
the overstrike is offset. For italic strings, the overhang is 
the amount the top of the font is skewed past the bottom 
of the font. 


The tmOverhang field allows the application to deter- 
mine how much of the character width returned by a 
GetTextExtent function call on a single character is the 
actual character width and how much is the per-string 
extra width. The actual width is the extent minus the 
overhang. 


tmDigitizedAspectX Specifies the horizontal aspect of the device for which 
the font was designed. 


tmDigitizedAspectY Specifies the vertical aspect of the device for which the 
font was designed. The ratio of the tmDigitizedAspectX 
and tmDigitizedAspectY fields is the aspect ratio of the 
device for which the font was designed. 


The GetDeviceCaps and GetTextMetrics functions in Chapter 4, “Functions Directory,” 
in Reference, Volume 1. 
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WNDCLASS 


Window-Class Data Structure 


The WNDCLASS structure contains the class attributes that are registered by the 
RegisterClass function. 


typedef struct tagWNDCLASS { 
WORD style; 
long (FAR PASCAL *IpfnWndProc)(); 
baie cbC1sExtra; 
int cbWndExtra; 
HANDLE hInstance; 
HICON hicon; 
HCURSOR hCursor; 
HBRUSH  hbrBackground; 
LPSTR lpszMenuName; 
LPSTR lpszClassName; 

} WNDCLASS; 


The WNDCLASS structure has the following fields: 


Field Description 


style Specifies the class style. These styles can be combined by using 
the bitwise OR operator. The style field can be any combination 
of the following values: 


Value Meaning 

CS_BYTEALIGNCLIENT Aligns a window’s client area 
on the byte boundary (in the 
x direction). 


CS_BYTEALIGNWINDOW Aligns a window on the byte 
boundary (in the x direction). 


CS_CLASSDC Gives the window class its 
own display context (shared 
by instances). 


CS_DBLCLKS Sends double-click messages 
to a window. 
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Field Description 


Value 


CS_GLOBALCLASS 


CS_HREDRAW 
CS_NOCLOSE 


CS_OWNDC 


CS_PARENTDC 


Meaning 


Specifies that the window 
class is an application global 
class. An application global 
class is created by an applica- 
tion or library and is 
available to all applications. 
The class is destroyed when 
the application or library that 
created the class terminates; 
it is essential, therefore, that 
all windows created with the 
application global class be 
closed before this occurs. 


Redraws the entire window if 
the horizontal size changes. 


Inhibits the close option on 
the System menu. 


Gives each window instance 
its own display context. Note 
that although the 
CS_OWNDC style is con- 
venient, it must be used with 
discretion because each dis- 
play context occupies 
approximately 800 bytes of 
memory. 


Gives the parent window’s 
display context to the 
window class. 


WNDCLAS 


Field 


IpfnWndProc 
cbClsExtra 


cbWndExtra 


hInstance 


Description 


Value 


CS_SAVEBITS 


CS_VREDRAW 


Points to the window function. 


7-64 


Meaning 


Saves the portion of the 
screen image that is obscured 
by a window; Windows uses 
the saved bitmap to re-create 
a screen image when the 
window is removed. 
Windows displays the bitmap 
at its original location and 
does not send WM_PAINT 
messages to windows which 
had been obscured by the 
window if the memory used 
by the bitmap has not been 
discarded and if other screen 
actions have not invalidated 
the stored image. An applica- 
tion should set this bit only 
for small windows that are 
displayed briefly and then re- 
moved before much other 
screen activity takes place. 
Setting this bit for a window 
increases the amount of time 
required to display the 
window due to the time re- 
quired to allocate memory to 
store the bitmap. 


Redraws the entire window if 
the vertical size changes. 


Specifies the number of bytes to allocate following the window- 


class structure. 


Specifies the number of bytes to allocate following the window 
instance. If an application is using the WNDCLASS structure to 
register a dialog box created with the CLASS directive in the 
-RC script file, it must set this field to DLGWINDOWEXTRA. 


Identifies the class module. The hInstance field must be an in- 
stance handle and must not be NULL. 
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Field 


hIcon 


hCursor 


hbrBackground 


Description 


Identifies the class icon. The hIcon field must be a handle to an 
icon resource. If hIcon is NULL, the application must draw an 
icon whenever the user minimizes the application’s window. 


Identifies the class cursor. The hCursor field must be a handle 

to a cursor resource. If hCursor is NULL, the application must 
explicitly set the cursor shape whenever the mouse moves into 

the application’s window. 


Identifies the class background brush. The hbrBackground 
field can be either a handle to the physical brush that is to be 
used for painting the background, or it can be a color value. Ifa 
color value is given, it must be one of the standard system colors 
listed below, and the value 1 must be added to the chosen color 
(for example, COLOR_BACKGROUND + 1 specifies the sys- 
tem background color). If a color value is given, it must be 
converted to one of the following HBRUSH types: 


COLOR_ACTIVEBORDER 
COLOR_ACTIVECAPTION 
COLOR_APPWORKSPACE 
COLOR_BACKGROUND 
COLOR_BTNFACE 
COLOR_BTNSHADOW 
COLOR_BTNTEXT 
COLOR_CAPTIONTEXT 
COLOR_GRAYTEXT 
COLOR_HIGHLIGHT 
COLOR_HIGHLIGHTTEXT 
COLOR_INACTIVEBORDER 
COLOR_INACTIVECAPTION 
COLOR_MENU 
COLOR_MENUTEXT 
COLOR_SCROLLBAR 
COLOR_WINDOW 
COLOR_WINDOWFRAME 
COLOR_WINDOWTEXT 


When hbrBackground is NULL, the application must paint its 
own background whenever it is requested to paint in its client 
area. The application can determine when the background needs 
painting by processing the WM_ERASEBKGND message or by 
testing the fErase field of the PAINTSTRUCT structure filled 
by the BeginPaint function. 


WNDCLASS 


Field 


IpszMenuName 


IpszClassName 


7-66 


Description 


Points to a null-terminated character string that specifies the 
resource name of the class menu (as the name appears in the 
resource file). If an integer is used to identify the menu, the 
MAKEINTRESOURCE macro can be used. If the 
IpszMenuName field is NULL, windows belonging to this class 
have no default menu. 


Points to a null-terminated character string that specifies the 
name of the window class. 
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This chapter describes the statements that define resources that the Microsoft 
Windows Resource Compiler (RC) adds to an application’s executable file. See 
Tools for information on running the Resource Compiler. 


This chapter describes resource script statements in the following categories: 


m Single-line statements 

= User-defined resources 

= RCDATA statement 

= STRINGTABLE statement 

= ACCELERATORS statement 
= Menu statements 

= Dialog statements 


m Directives 


8.1 Single-Line Statements 


The single-line statements define resources that are contained in a single file, 
such as cursors, icons, and fonts. The statements associate the filename of the 
resource with an identifying name or number. The resource is added to the exe- 
cutable file when the application is created, and can be extracted during execu- 
tion by referring to the name or number. 


The following is the general form for all single-line statements: 


namelD resource-type [[load-option]| [[mem-option] filename 


The namelD field specifies either a unique name or an integer value identifying 
the resource. For a font resource, nameID must be a number; it cannot be a name. 


The resource-type field specifies one of the following key words, which identify 
the type of resource to be loaded: 
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Key word Resource Type 

CURSOR Specifies a bitmap that defines the shape of the 
cursor on the display screen. 

ICON Specifies a bitmap that defines the shape of the icon 
to be used for a given application. 

BITMAP Specifies a custom bitmap that an application is 
going to use in its screen display or as an item ina 
menu. 

FONT Specifies a file that contains a font. 


The optional /oad-option field takes a key word that specifies when the resource 
is to be loaded. The key word must be one of the following: 


Option Description 

PRELOAD Resource is loaded immediately. 

LOADONCALL Resource is loaded when called. This is the default 
option. 


NOTE \conand cursor resources can contain more than one image. If the resource is 
marked as PRELOAD, Windows loads all images in the resource when the application ex- 
ecutes. 


The optional mem-option field takes the following key word or key words, which 
specify whether the resource is fixed or moveable and whether it is discardable: 


Option Description 

FIXED Resource remains at a fixed memory location. 

MOVEABLE Resource can be moved if necessary in order to 
compact memory. 

DISCARDABLE Resource can be discarded if no longer needed. 


The default is MOVEABLE and DISCARDABLE for cursor, icon, and font 
resources. The default for bitmap resources is MOVEABLE. 


The filename field is an ASCII string that specifies the DOS filename of the file 
that contains the resource. A full pathname must be given if the file is not in the 
current working directory. 
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The following example demonstrates the correct usage for a single-line statement: 


cursor CURSOR point.cur 
cursor CURSOR DISCARDABLE point.cur 
19 CURSOR custom.cur 


desk ICON desk.ico 
desk ICON DISCARDABLE desk.ico 
Tl: ICON custom.ico 


disk BITMAP disk.bmp 
disk BITMAP DISCARDABLE disk.bmp 
2 BITMAP custom.bmp 


5 FONT CMROMAN. FNT 


8.2 User-Defined Resources 


An application can also define its own resource. The resource can be any data 
that the application intends to use. A user-defined resource statement has the fol- 
lowing form: 


namelD typelD [[load-option]| [mem-option] {[[filename] | 
[BEGIN 

raw-data 

END]} 


The namelD field specifies either a unique name or an integer value that identi- 
fies the resource. 


The typelD field specifies either a unique name or an integer value that identifies 
the resource type. If a number is given, it must be greater than 255. The numbers 
1 through 255 are reserved for existing and future predefined resource types. 


The optional /oad-option field takes a key word that specifies when the resource 
is to be loaded. The key word must be one of the following: 


Option Description 

PRELOAD Resource is loaded immediately. 

LOADONCALL Resource is loaded when called. This is the default 
option. 


The optional mem-option field takes the following key word or key words, which 
specify whether the resource is fixed or moveable and whether it is discardable: 
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Option Description 
FIXED Resource remains at a fixed memory location. 
MOVEABLE Resource can be moved if necessary in order to com- 


pact memory. This is the default option. 


DISCARDABLE Resource can be discarded if it is no longer needed. 


The optional filename field is an ASCII string that specifies the DOS filename of 
the file that contains the resource. A full pathname must be given if the file is not 
in the current working directory. Do not use the filename field if you supply raw 
data between the optional BEGIN and END statements. 


The raw-data field specifies one or more integers and strings. Integers can be in 
decimal, octal, or hexadecimal format. Do not use raw-data field and the BEGIN 
and END statements if you specify a filename. 


The following example demonstrates the correct usage for user-defined state- 
ments: 


array MYRES  data.res 


14 300 custom.res 
18 MYRES2 
BEGIN 


"Here is a data string\@", /* A string. Note: explicitly 
null-terminated */ 


1024, cL Ait */ 
OxO29a, /* hex int */ 
00733, (* octal iit. 
"NGL" /* octal byte */ 

END 

8.3 RCDATA Statement 

Syntax 

nameID RCDATA [load-option] [[mem-option] 

BEGIN 

raw-data 

END 


The RCDATA statement defines a raw data resource for an application. Raw 
data resources permit the inclusion of binary data directly in the executable file. 


The namelD field specifies either a unique name or an integer value that identi- 
fies the resource. 


The optional /oad-option field takes a key word that specifies when the resource 
is to be loaded. It must be one of the following: 


Resource Script Statements 8-5 


Option Description 

PRELOAD Resource is loaded immediately. 

LOADONCALL Resource is loaded when called. This is the default 
option. 


The optional mem-option field takes the following key word or key words, which 
specify whether the resource is fixed or moveable and whether it is discardable: 


Option Description 

FIXED Resource remains at a fixed memory location. 

MOVEABLE Resource can be moved if necessary in order to 
compact memory. 

DISCARDABLE Resource can be discarded if no longer needed. 


The default is MOVEABLE and DISCARDABLE. 


The raw-data field specifies one or more integers and strings. Integers can be in 
decimal, octal, or hexadecimal format. 


The following example demonstrates the correct usage for the RCDATA 
statement: 


resname RCDATA 
BEGIN 
"Here is a data string\®", /* A string. Note: explicitly 
null-terminated */ 


1024, /* int “iy 
9xO29a, /* hex int By) 
60733, /-octal int. #/ 
"NOK /* octal byte */ 

END 

8.4 STRINGTABLE Statement 

Syntax 

STRINGTABLE [[oad-option]| [[mem-option]] 

BEGIN 

stringID string 

END 


The STRINGTABLE statement defines one or more string resources for an 
application. String resources are simply null-terminated ASCII strings that can be 
loaded when needed from the executable file, using the LoadString function. 
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The optional /oad-option field takes a key word that specifies when the resource 
is to be loaded. It must be one of the following: 


Option Description 

PRELOAD Resource is loaded immediately. 

LOADONCALL Resource is loaded when called. This is the default 
option. 


The optional mem-option field takes the following key word or key words, which 
specify whether the resource is fixed or moveable and whether or not it is discard- 


able: 

Option Description 

FIXED Resource remains at a fixed memory location. 

MOVEABLE Resource can be moved if necessary in order to com- 
pact memory. 

DISCARDABLE Resource can be discarded if no longer needed. 


The default is MOVEABLE and DISCARDABLE. 
The stringID field specifies an integer value that identifies the resource. 


The string field specifies one or more ASCII strings, enclosed in double quota- 
tion marks. The string must be no longer than 255 characters and must occupy a 
single line in the source file. To add a carriage return to the string, use this 
character sequence: \012. For example, “Line one\012Line two” would define a 
string that would be displayed as follows: 


Line one 
Line two 


Grouping strings in separate segments allows all related strings to be read in at 
one time and discarded together. When possible, an application should make the 
table moveable and discardable. The Resource Compiler allocates 16 strings per 
segment and uses the identifier value to determine which segment is to contain 
the string. Strings with the same upper 12 bits in their identifiers are placed in the 
same segment. 


The following example demonstrates the correct usage of the STRINGTABLE 
statement: 


#define IDS_HELLO 1 
#tdefine IDS_GOODBYE 2 


STRINGTABLE 
BEGIN 
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IDS_HELLO, "Hello" 
IDS_GOODBYE, "Goodbye" 
END 
8.5 ACCELERATORS Statement 
Syntax 
acctablename ACCELERATORS 
BEGIN 


event, idvalue, [[type]] [NOINVERT] [ALT] [SHIFT] [CONTROL] 


END 


The ACCELERATORS statement defines one or more accelerators for an appli- 
cation. An accelerator is a key stroke defined by the application to give the user a 
quick way to perform a task. The TranslateAccelerator function is used to trans- 
late accelerator messages from the application queue into WM_COMMAND or 
WM_SYSCOMMAND messages. 


The acctablename field specifies either a unique name or an integer value that 
identifies the resource. 


The event field specifies the key stroke to be used as an accelerator. It can be any 
one of the following: 


Character Description 
“char” A single ASCII character enclosed in double quotes. 


The character can be preceded by a caret (“), 
meaning that the character is a control character. 


ASCII character An integer value representing an ASCII character. 
The type field must be ASCII. 


Virtual key character An integer value representing a virtual key. The vir- 
tual key for alphanumeric keys can be specified by 
placing the uppercase letter or number in double quo- 
tation marks (for example, “9” or “C”). The type 
field must be VIRTKEY. 


The idvalue field specifies an integer value that identifies the accelerator. 


The type field is required only when event is an ASCII character or a virtual key 
character. The type field specifies either ASCII or VIRTKEY; the integer value 
of event is interpreted accordingly. When VIRTKEY is specified and the event 
field contains a string, the event field must be uppercase. 
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The NOINVERT option, if given, means that no top-level menu item is 
highlighted when the accelerator is used. This is useful when defining accel- 
erators for actions such as scrolling that do not correspond to a menu item. If 
NOINVERT is omitted, a top-level menu item will be highlighted (if possible) 
when the accelerator is used. 


The ALT option, if given, causes the accelerator to be activated only if the ALT 
key is down. 


The SHIFT option, if given, causes the accelerator to be activated only if the 
SHIFT key is down. 


The CONTROL option, if given, defines the character as a control character (the 
accelerator is only activated if the CONTROL key is down). This has the same ef- 
fect as using a caret (*) before the accelerator character in the event field. 


The ALT, SHIFT, and CONTROL options apply only to virtual keys. 
The following example demonstrates the correct usage of accelerator keys: 


1 ACCELERATORS 


BEGIN 
race, LDDGLEAR ; control C 
bel ou IDDCLEAR ; shift K 
Oe as TDODELLTPSER SALT .3alt 
98, IDDRECT, ASCII a) 
66, IDDSTAR, ASCII : B shift. b) 
Eres DDRECT A | 
"Giang IDDSTAR : Gitshift.G) 
VK_F1, IDDCLEAR, VIRTKEY Fal 
VK_Fl, IDDSTAR, CONTROL, VIRTKEY * contro), Fl 
VK_F1, IODEULIPSE,. SHIFT, VIRTKEY < shattes Fl 
VK_F1, IDDRECT, ALT, VIRTKEY salt Fl 
VK_F2, IDDCLEAR, ALT, SHIFT, VIRTKEY ; alt shift F2 
VK_F2, IDDSTAR, CONTROL, SHIFT, VIRTKEY ; ctrl shift F2 
VK_F2, IDDRECT, ALT, CONTROL, VIRTKEY ; alt control F2 

END 

8.6 MENU Statement 

Syntax 

menulD MENU [[load-option]] [[mem-option]] 

BEGIN 

item-definitions 

END 


The MENU statement defines the contents of a menu resource. A menu resource 
is a collection of information that defines the appearance and function of an appli- 
cation menu. A menu is a special input tool that lets a user select commands from 
a list of command names. 
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The menulD field specifies a name or number used to identify the menu resource. 


The optional /oad-option field takes a key word that specifies when the resource 
is to be loaded. It must be one of the following: 


Option Description 

PRELOAD Resource is loaded immediately. 

LOADONCALL Resource is loaded when called. This is the default 
option. 


The optional mem-option field takes the following key word or key words, which 
specify whether the resource is fixed or moveable and whether it is discardable: 


Option Description 

FIXED Resource remains at a fixed memory location. 

MOVEABLE Resource can be moved if necessary in order to com- 
pact memory. 

DISCARDABLE Resource can be discarded if no longer needed. 


The default is MOVEABLE and DISCARDABLE. 


The item-definition field specifies special resource statements that define the 
items in the menu. These statements are defined in the following sections. 


The following is an example of a complete MENU statement: 


sample MENU 
BEGIN 
MENUITEM "&Soup", 180 
MENUITEM "S&alad", 101 
POPUP "&Entree" 
BEGIN 
MENUITEM "&Fish", 200 
MENUITEM "&Chicken", 201, CHECKED 
POPUP "&Beef" 
BEGIN 
MENUITEM "&Steak", 301 
MENUITEM "&Prime Rib", 392 
END 
END 
MENUITEM "&Dessert", 103 
END 
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8.6.1 ltem-Definition Statements 


The MENUITEM and POPUP statements are used in the item-definition section 
of a MENU statement to define the names and attributes of the actual menu 
items. Any number of statements can be given; each defines a unique item. The 
order of the statements defines the order of the menu items. 


The MENUITEM and POPUP statements can be used only within an item-defi- 
nition section of a MENU statement. 


MENUITEM Statement 


Syntax 
MENUITEM text, result, [optionlist]] 


This optional statement defines a menu item. 


The text field takes an ASCII string, enclosed in double quotation marks, that 
specifies the name of the menu item. 


The string can contain the escape characters \t and \a. The \t character inserts a 
tab in the string and is used to align text in columns. Tab characters should be 
used only in pop-up menus, not in menu bars. (See the following section for infor- 
mation on pop-up menus.) The \a character aligns all text that follows it flush 
right to the menu bar or pop-up menu. 


To insert a double quotation mark (") in the string, use two double quotation 
marks ("""). 


To add a mnemonic to the text string, place the ampersand (&) ahead of the letter 
that will be the mnemonic. This will cause the letter to appear underlined in the 
control and to function as the mnemonic. To use the ampersand as a character in 
a string, insert two ampersands (&&). 


The result field takes an integer value that specifies the result generated when the 
user selects the menu item. Menu-item results are always integers; when the user 
clicks the menu-item name, the result is sent to the window that owns the menu. 


The optional optioniist field takes one or more predefined menu options, sepa- 
rated by commas or spaces, that specify the appearance of the menu item. The 
menu options are as follows: 


Option Description 
CHECKED Item has a checkmark next to it. 
GRAYED Item name is initially inactive and appears on the 


menu in gray or a lightened shade of the menu-text 
color. 
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Option Description 
HELP Item has a vertical separator to its left. 
INACTIVE Item name is displayed, but it cannot be selected. 


MENUBARBREAK Same as MF_MENUBREAK except that for pop-up 
menus, it separates the new column from the old 
column with a vertical line. 


MENUBREAK Places the menu item on a new line for static menu- 
bar items. For pop-up menus, places the menu item 
in a new column, with no dividing line between the 
columns. 


The INACTIVE and GRAYED options cannot be used together. 


The following example demonstrates the correct usage of the MENUITEM state- 
ment: 


MENUITEM "&Alpha", 1, CHECKED, GRAYED 
MENUITEM "&Beta", 2 


POPUP Statement 


Syntax 


POPUP text, [optionlist]] 
BEGIN 

item-definitions 

END 


This statement marks the beginning of the definition of a pop-up menu. A pop-up 
menu (which is also known as a drop-down menu) is a special menu item that dis- 
plays a sublist of menu items when it is selected. 


The text field takes an ASCII string, enclosed in double quotation marks, that 
specifies the name of the pop-up menu. 


The optional optionlist field takes one or more predefined menu options that 
specify the appearance of the menu item. The menu options are as follows: 


Option Description 
CHECKED Item has a checkmark next to it. This option is not 


valid for a top-level pop-up menu. 


GRAYED Item name is initially inactive and appears on the 
menu in gray or a lightened shade of the menu-text 
color. 
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Option Description 
INACTIVE Item name is displayed, but it cannot be selected. 


MENUBARBREAK Same as MF_MENUBREAK except that for pop-up 
menus, it separates the new column from the old 
column with a vertical line. 


MENUBREAK Places the menu item on a new line for static menu- 
bar items. For pop-up menus, places the menu item 
in a new column, with no dividing line between the 
columns. 


The options can be combined using the bitwise OR operator. The INACTIVE 
and GRAYED options cannot be used together. 


The item-definitions field can specify any number of MENUITEM or POPUP 
statements. As a result, any pop-up menu item can display another pop-up menu. 


The following example demonstrates the correct usage of the POPUP statement: 


chem MENU 
BEGIN 


POPUP "&Elements"™ 

BEGIN 
MENUITEM "&Oxygen", 200 
MENUITEM "&Carbon", 201, CHECKED 
MENUITEM "&Hydrogen", 202 
MENUITEM "&Sulfur", 203 
MENUITEM "Ch&lorine", 204 


END 
POPUP "&Compounds" 
BEGIN 
POPUP "&Sugars" 
BEGIN 
MENUITEM "&Glucose", 3@1 
MENUITEM "&Sucrose", 302, CHECKED 
MENUITEM "&Lactose", 303, MENUBREAK 
MENUITEM "&Fructose", 304 
END 


POPUP "&Acids" 

BEGIN 
"&Hydrochloric", 401 
"&Sulfuric", 402 

END 


END 


END 
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MENUITEM SEPARATOR Statement 


Syntax 
MENUITEM SEPARATOR 


This special form of the MENUITEM statement creates an inactive menu item 
that serves as a dividing bar between two active menu items in a pop-up menu. 


The following demonstrates the correct usage of the MENUITEM SEPARA- 
TOR statement: 


MENUITEM "&Roman", 206 
MENUITEM SEPARATOR 
MENUITEM "&2@ Point", 301 


8.7 DIALOG Statement 


The DIALOG statement defines a template that can be used by an application to 
create dialog boxes. 


Syntax 


nameID DIALOG [[load-option]] [[mem-option]] x, y, width, height 
[loption-statements]] 

BEGIN 

control-statements 

END 


This statement marks the beginning of a DIALOG template. It defines the name 
of the dialog box, the memory and load options, the box’s starting location on the 
display screen, and the box’s width and height. 


The namelD field specifies either a unique name or an integer value that identi- 
fies the resource. 


The optional /oad-option field takes a key word that specifies when the resource 
is to be loaded. It must be one of the following: 


Option Description 

PRELOAD Resource is loaded immediately. 

LOADONCALL Resource is loaded when called. This is the default 
option. 


The optional mem-option field takes the following key word or key words, which 
specify whether the resource is fixed or moveable and whether it is discardable: 
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Option Description 

FIXED Resource remains at a fixed memory location. 

MOVEABLE Resource can be moved if necessary in order to com- 
pact memory. This is the default option. 

DISCARDABLE Resource can be discarded if no longer needed. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the dialog box. The horizontal units are 14 of the dialog base 
width unit; the vertical units are 1% of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The exact meaning of the coordinates depends on the style defined by the 
STYLE option statement. For child-style dialog boxes, the coordinates are rela- 
tive to the origin of the parent window, unless the dialog box has the style 
DS_ABSALIGN; in that case, the coordinates are relative to the origin of the dis- 
play screen. 


The width and height fields take integer values that specify the width and height 
of the box. The width units are 4 of the dialog base width unit; the height units 
are 1% of the dialog base height unit. 


The option and control statements are described in the following sections. 
The following demonstrates the correct usage of the DIALOG statement: 


dHinclude "WINDOWS.H" 


errmess DIALOG 10, 19, 300, 119 

STYLE WS_POPUP|WS_BORDER 

CAPTION “Error!" 

BEGIN 
CTEXT "Select One:", 1, 10, 10, 280, 12 
RADIOBUTTON "&Retry", 2, 75, 30, 68, 12 
RADIOBUTTON "&Abort", 3, 75, 50, 60, 12 
RADIOBUTTON "&Ignore", 4, 75, 80, 6, 12 

END 


Comments 


Do not use the WS_CHILD style with a modal dialog box. The DialogBox func- 
tion always disables the parent/owner of the newly-created dialog box. When a 
parent window is disabled, its child windows are implicitly disabled. Since the 
parent window of the child-style dialog box is disabled, the child-style dialog 
box is too. 


If a dialog box has the DS_ABSALIGN style, the dialog coordinates for its 
upper-left corner are relative to the screen origin instead of to the upper-left 
corner of the parent window. You would typically use this style when you 
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wanted the dialog box to start in a specific part of the display no matter where the 
parent window may be on the screen. 


The name DIALOG can also be used as the class-name parameter to the 
CreateWindow function in order to create a window with dialog-box attributes. 


8.7.1 Dialog Option Statements 


The dialog option statements, given in the option-statements section of the 
DIALOG statement, define special attributes of the dialog box, such as its style, 
caption, and menu. The option statements are optional. If the application does not 
supply a particular option statement, the dialog box is given default attributes for 
that option. Dialog option statements include the following: 

a STYLE 

a CAPTION 

a MENU 

= CLASS 


= FONT 


The option statements are discussed individually in the following sections. 


STYLE Statement 


Syntax 
STYLE style 


This optional statement defines the window style of the dialog box. The window 
style specifies whether the box is a pop-up or a child window. The default style 
has the following attributes: 


WS_POPUP 
WS_BORDER 
WS_SYSMENU 


The style field takes an integer value or predefined name that specifies the 
window style. It can be any of the window styles defined in Table 8.1, “Window 
Styles.” 


Comments 


If the predefined names are used, the #include directive must be used so that the 
WINDOWS.H file will be included in the resource script. 
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Table 8.1 Window Styles 


Style Meaning 


DS_LOCALEDIT Specifies that edit controls in the dialog box will 
use memory in the application’s data segment. By 
default, all edit controls in dialog boxes use 
memory outside the application’s data segment. 
This feature can be suppressed by adding the 
DS_LOCALEDIT flag to the STYLE command 
for the dialog box. If this flag is not used, 
EM_GETHANDLE and EM_SETHANDLE mes- 
sages must not be used since the storage for the 
control is not in the application’s data segment. 
This feature does not affect edit controls created 
outside of dialog boxes. 


DS_MODALFRAME Creates a dialog box with a modal dialog-box 
frame that can be combined with a title bar and 
system menu by specifying the WS_CAPTION 
and WS_SYSMENU styles. 


DS_NOIDLEMSG Suppresses WM_ENTERIDLE messages that 
Windows would otherwise send to the owner of 
the dialog box while the dialog box is displayed. 


DS_SYSMODAL Creates a system-modal dialog box. 

WS_BORDER Creates a window that has a border. 

WS_CAPTION Creates a window that has a title bar (implies 
WS_BORDER). 

WS_CHILD Creates a child window. It cannot be used with 
WS_POPUP. 

WS_CHILDWINDOW Creates a child window that has the style 
WS_CHILD. 

WS_CLIPCHILDREN Excludes the area occupied by child windows 


when drawing within the parent window. Used 
when creating the parent window. 


WS_CLIPSIBLINGS Clips child windows relative to each other; that is, 
when a particular child window receives a 
WP_PAINT message, this style clips all other top- 
level child windows out of the region of the child 
window to be updated. (If WS_CLIPSIBLINGS is 
not given and child windows overlap, it is 
possible, when drawing in the client area of a 
child window, to draw in the client area of a neigh- 
boring child window.) For use with WS_CHILD 


only. 
WS_DISABLED Creates a window that is initially disabled. 
WS_DLGFRAME Creates a window with a modal dialog-box frame 


but no title. 
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Table 8.1 Window Styles (continued) 

Style Meaning 

WS_GROUP Specifies the first control of a group of controls in 
which the user can move from one control to the 
next by using the arrow keys. All controls defined 
with the WS_GROUP style after the first control 
belong to the same group. The next control with 
the WS_GROUP style ends the style group and 
starts the next group (i.e., one group ends where 
the next begins). This style is valid only for con- 
trols. 

WS_HSCROLL Creates a window that has a horizontal scroll bar. 

WS_ICONIC Creates a window that is initially iconic. For use 
with WS_OVERLAPPED only. 

WS_MAXIMIZE Creates a window of maximum size. 

WS_MAXIMIZEBOX Creates a window that has a Maximize box. 

WS_MINIMIZE Creates a window of minimum size. 


WS_MINIMIZEBOX 
WS_OVERLAPPED 


WS_OVERLAPPEDWINDOW 


WS_POPUP 


WS_POPUPWINDOW 


WS_SIZEBOX 


WS_SYSMENU 


WS_TABSTOP 


Creates a window that has a Minimize box. 


Creates an overlapped window. An overlapped 
window has a caption and a border. 


Creates an overlapped window having the 
WS_OVERLAPPED, WS_CAPTION, WS_SYS- 
MENU, WS_THICKFRAME, 
WS_MINIMIZEBOX, and WS_MAXIMIZE- 
BOX styles. 


Creates a pop-up window. It cannot be used with 
WS_CHILD. 


Creates a pop-up window that has the styles 
WS_POPUP, WS_BORDER, and WS_SYS- 
MENU. The WS_CAPTION style must be 
combined with the WS_POPUPWINDOW style 
to make the system menu visible. 


Creates a window that has a size box. Used only 
for windows with a title bar or with vertical and 
horizontal scroll bars. 


Creates a window that has a System-menu box in 
its title bar. Used only for windows with title bars. 
If used with a child window, this style creates a 
Close box instead of a System-menu box. 


Specifies one of any number of controls through 
which the user can move by using the TAB key. 
The TAB key moves the user to the next control 
specified by the WS_TABSTOP style. This style 
is valid only for controls. 
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Table 8.1 | Window Styles (continued) 


Style Meaning 

WS_THICKFRAME Creates a window with a thick frame that can be 
used to size the window. 

WS_VISIBLE Creates a window that is initially visible. This ap- 


plies to overlapping and pop-up windows. For 
overlapping windows, the y parameter is used as a 
Show Window function parameter. 


WS_VSCROLL Creates a window that has a vertical scroll bar. 


CAPTION Statement 


Syntax 
CAPTION captiontext 


This optional statement defines the dialog box’s title. The title appears in the 
box’s caption bar (if it has one). 


The default caption is empty. 


The captiontext field specifies an ASCII character string enclosed in double quo- 
tation marks. 


The following example demonstrates the correct usage of the CAPTION state- 
ment: 


CAPTION "Error!" 


MENU Statement 


Syntax 
MENU menuname 


This optional statement defines the dialog box’s menu. If no statement is given, 
the dialog box has no menu. 


The menuname field specifies the resource name or number of the menu to be 
used. 


The following example demonstrates the correct usage of the MENU statement: 


MENU errmenu 
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CLASS Statement 


Syntax 
CLASS class 


This optional statement defines the class of the dialog box. If no statement is 
given, the Windows standard dialog class will be used as the default. 


The class field specifies an integer or a string, enclosed in double quotation 
marks, that identifies the class of the dialog box. If the window procedure for the 
class does not process a message sent to it, it must call the DefDlgProc function 
to ensure that all messages are handled properly for the dialog box. A private 
class can use DefDlgProc as the default window procedure. The class must be 
registered with the cb WndExtra field of the WNDCLASS data structure set to 
DLGWINDOWEXTRA. 


The following example demonstrates the correct usage of the CLASS statement: 


CLASS “myclass" 


Comments 


The CLASS statement should be used with special cases, since it overrides the 
normal processing of a dialog box. The CLASS statement converts a dialog box 
to a window of the specified class; depending on the class, this could give un- 
desirable results. Do not use the predefined control class names with this state- 
ment. 


FONT Statement 


Syntax 
FONT pointsize, typeface 


This optional statement defines the font with which Windows will draw text in 
the dialog box. The font must have been previously loaded, either from WIN.INI 
or by calling LoadFont. 


The pointsize field is an integer that specifies the size in points of the font. 


The typeface field specifies an ASCII character string enclosed in double quota- 
tion marks that specifies the name of the typeface. This name must be identical to 
the name defined in the [fonts] section of WIN.INI. 


The following example demonstrates the correct usage of the FONT statement: 


FONT U2z0 Shelve 
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8.7.2 Dialog Control Statements 


The dialog control statements, given in the control-statements section of the 
DIALOG statement, define the attributes of the control windows that appear in 
the dialog box. A dialog box is empty unless one or more control statements are 
given. Control statements include the following: 


= LTEXT 

= RTEXT 

a CTEXT 

= CHECKBOX 

= PUSHBUTTON 

= LISTBOX 

= GROUPBOX 

= DEFPUSHBUTTON 
= RADIOBUTTON 

= EDITTEXT 

= COMBOBOX 

= ICON 

= SCROLLBAR 

= CONTROL 

The control statements are discussed individually in the following sections. For 


more information on control classes and styles, see Tables 8.2, “Control 
Classes,” and 8.3, “Control Styles.” 


LTEXT Statement 


Syntax 
LTEXT text, id, x, y, width, height, [[style]] 


This statement defines a flush-left text control. It creates a simple rectangle that 
displays the given text flush-left in the rectangle. The text is formatted before it is 
displayed. Words that would extend past the end of a line are automatically 
wrapped to the beginning of the next line. 


The text field takes an ASCII string that specifies the text to be displayed. The 
string must be enclosed in double quotation marks. To add a mnemonic to the 
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text string, place the ampersand (&) ahead of the letter that will be the mne- 
monic. To use the ampersand as a character in a string, insert two ampersands 
(&&). 


The id field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are 4 of the dialog base 
width unit; the vertical units are 1g of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 4 of the dialog base width unit; the height 
units are 1 of the dialog base height unit. 


The optional style field can contain any combination (or none) of the following 
styles: 

a WS_TABSTOP 

= WS_GROUP 


These styles are described in Table 8.1, “Window Styles.” Styles can be com- 
bined using the bitwise OR operator. 


Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for LTEXT is SS_LEFT and WS_GROUP. 
The following example demonstrates the correct usage of the LTEXT statement: 


LTEXT "Enter Name:", 3, 10, 10, 40, 10 


RTEXT Statement 


Syntax 
RTEXT text, id, x, y, width, height, [[style]] 


This statement defines a flush-right text control. It creates a simple rectangle that 
displays the given text flush-right in the rectangle. The text is formatted before it 
is displayed. Words that would extend past the end of a line are automatically 
wrapped to the beginning of the next line. 


The text field takes an ASCII string that specifies the text to be displayed. The 
string must be enclosed in double quotation marks. To add a mnemonic to the 
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text string, place the ampersand (&) ahead of the letter that will be the mne- 
monic. To use the ampersand as a character in a string, insert two ampersands 
(&&). 


The id field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are 4 of the dialog base 
width unit; the vertical units are 1 of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 14 of the dialog base width unit; the height 
units are 1 of the dialog base height unit. 


The optional style field can contain any combination (or none) of the following 
styles: 

a WS_TABSTOP 

m WS_GROUP 


These styles are described in Table 8.1, “Window Styles.” Styles can be com- 
bined using the bitwise OR operator. 


Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for RTEXT is SS_RIGHT and WS_GROUP. 
The following example demonstrates the correct usage of the RTEXT statement: 


RTEXT "Number of Messages", 4, 30, 5@, 100, 1 


CTEXT Statement 


Syntax 
CTEXT text, id, x, y, width, height, [[style]] 


This statement defines a centered text control. It creates a simple rectangle that 
displays the given text centered in the rectangle. The text is formatted before it is 
displayed. Words that would extend past the end of a line are automatically 
wrapped to the beginning of the next line. 


The text field takes an ASCII string that specifies the text to be displayed. The 
string must be enclosed in double quotation marks. To add a mnemonic to the 
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text string, place the ampersand (&) ahead of the letter that will be the mne- 
monic. To use the ampersand as a character in a string, insert two ampersands 
(&&). 


The id field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are 14 of the dialog base 
width unit; the vertical units are 1% of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 14 of the dialog base width unit; the height 
units are 14 of the dialog base height unit. 


The optional style field can contain any combination (or none) of the following 
styles: 

a WS_TABSTOP 

a WS_GROUP 


These styles are described in Table 8.1, “Window Styles.” Styles can be com- 
bined using the bitwise OR operator. 


Commenis 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for CTEXT is SS_CENTER and WS_GROUP. 
The following example demonstrates the correct usage of the CTEXT statement: 


CTEXT “Title”, 3, 10, 50, 408, 10 


CHECKBOX Statement 


Syntax 
CHECKBOX text, id, x, y, width, height, [[style]] 


This statement defines a check-box control belonging to the BUTTON class. It 
creates a small rectangle (check box) that is highlighted when clicked. The given 
text is displayed just to the right of the check box. The control highlights the 
rectangle when the user clicks the mouse in it, and removes the highlight on the 
next click. 
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The text field takes an ASCII string that specifies the text to be displayed. The 
string must be enclosed in double quotation marks. To add a mnemonic to the 
text string, place the ampersand (&&) ahead of the letter that will be the mne- 
monic. To use the ampersand as a character in a string, insert two ampersands 
(&&). 


The id field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are 4 of the dialog base 
width unit; the vertical units are 18 of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBase Units function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 4 of the dialog base width unit; the height 
units are 1 of the dialog base height unit. 


The optional style field can contain any combination (or none) of the following 
styles: 


= WS_TABSTOP 
= WS_GROUP 


These styles are described in Table 8.1, “Window Styles.” 


In addition to these styles, the style field may contain any combination (or none) 
of the BUTTON-class styles described in Table 8.3, “Control Styles.” Styles can 
be combined using the bitwise OR operator. 

Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for CHECKBOX is BS_CHECKBOX and WS_TABSTOP. 


The following example demonstrates the correct usage of the CHECKBOX 
statement: 


CHECKBOX "Arabic", 3, 18, 10, 40, 10 
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PUSHBUTTON Statement 


Syntax 
PUSHBUTTON text, id, x, y, width, height, [[style]] 


This statement defines a push-button control belonging to the BUTTON class. It 
creates a rectangle containing the given text. The control sends a message to its 
parent whenever the user clicks the mouse inside the rectangle. 


The text field takes an ASCII string that specifies the text to be displayed. The 
string must be enclosed in double quotation marks. To add a mnemonic to the 
text string, place the ampersand (&) ahead of the letter that will be the mne- 
monic. To use the ampersand as a character in a string, insert two ampersands 
(&&). 


The id field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are 4 of the dialog base 
width unit; the vertical units are 1 of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 14 of the dialog base width unit; the height 
units are 8 of the dialog base height unit. 


The optional style field can contain any combination (or none) of the following 
styles: 

a WS_TABSTOP 

a WS_DISABLED 

= WS_GROUP 


These styles are described in Table 8.1, “Window Styles.” 


In addition to these styles, the style field may contain any combination (or none) 
of the BUTTON-class styles described in Table 8.3, “Control Styles.” Styles can 
be combined using the bitwise OR operator. 


Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for PUSHBUTTON is BS_PUSHBUTTON and WS_TAB- 
STOP. 
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The following example demonstrates the correct usage of the PUSHBUTTON 
statement: 


PUSHBUTTON "ON", 7, 18, 10, 20, 10 


LISTBOX Statement 


Syntax 
LISTBOX id, x, y, width, height, [[style]] 


This statement defines a list box belonging to the LISTBOX class. It creates a 
rectangle that contains a list of strings (such as filenames) from which the user 
can make selections. 


The id field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are 4 of the dialog base 
width unit; the vertical units are 1 of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 4 of the dialog base width unit; the height 
units are 1 of the dialog base height unit. 


The optional style field can contain any combination (or none) of the following 
styles: 

= WS_BORDER 

= WS_VSCROLL 


These styles are described in Table 8.1, “Window Styles.” 


In addition to these styles, the style field may contain any combination (or none) 
of the LISTBOX-class styles described in Table 8.3, “Control Styles.” Styles can 
be combined using the bitwise OR operator. 


Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for LISTBOX is LBS_NOTIFY, WS_VSCROLL, and 
WS_BORDER. 
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For information on the recommended keys for use in list-box controls, see the 
System Application Architecture, Common User Access: Advanced Interface 
Design Guide. 


The following example demonstrates the correct usage of the LISTBOX 
statement: 


LISTBOX 666, 10, 10, 58, 54 


GROUPBOX Statement 


Syntax 
GROUPBOX text, id, x, y, width, height, |[style]] 


This statement defines a group box belonging to the BUTTON class. It creates a 
rectangle that groups other controls together. The controls are grouped by draw- 
ing a border around them and displaying the given text in the upper-left corner. 


The text field takes an ASCII string that specifies the text to be displayed. The 
string must be enclosed in double quotation marks. To add a mnemonic to the 
text string, place the ampersand (&) ahead of the letter that will be the mne- 
monic. Selecting the mnemonic moves the input focus to the next control in the 
group, in the order set in the resource file. To use the ampersand as a character in 
a string, insert two ampersands (&&). 


The id field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are 4 of the dialog base 
width unit; the vertical units are 1 of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 4 of the dialog base width unit; the height 
units are 8 of the dialog base height unit. 


The optional style field can contain any combination (or none) of the following 
styles: 

= WS_TABSTOP 

= WS_DISABLED 


These styles are described in Table 8.1, “Window Styles.” 


In addition to these styles, the style field may contain any combination (or none) 
of the BUTTON-class styles described in Table 8.3, “Control Styles.” Styles can 
be combined using the bitwise OR operator. 
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Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for GROUPBOX is BS_GROUPBOX and WS_TABSTOP. 


The following example demonstrates the correct usage of the GROUPBOX state- 
ment: 


GROUPBOX "Output", 42, 10, 10, 30, 59 


DEFPUSHBUTTON Statement 


Syntax 
DEFPUSHBUTTON text, id, x, y, width, height, [[style]] 


This statement defines a default push-button control that belongs to the 
BUTTON class. It creates a small rectangle with a bold outline that represents 
the default response for the user. The given text is displayed inside the button. 
The control highlights the button in the usual way when the user clicks the mouse 
in it and sends a message to its parent window. 


The text field takes an ASCII string that specifies the text to be displayed. The 
string must be enclosed in double quotation marks. To add a mnemonic to the 
text string, place the ampersand (&) ahead of the letter that will be the mne- 
monic. To use the ampersand as a character in a string, insert two ampersands 
(&&). 


The id field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are 4 of the dialog base 
width unit; the vertical units are 1 of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 14 of the dialog base width unit; the height 
units are 8 of the dialog base height unit. 


The optional style field can contain any combination (or none) of the following 
styles: 


= WS_TABSTOP 
= WS_GROUP 
g WS_DISABLED 
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These styles are described in Table 8.1, “Window Styles.” 


In addition to these styles, the style field may contain any combination (or none) 
of the BUTTON-class styles described in Table 8.3, “Control Styles.” Styles can 
be combined using the bitwise OR operator. 


Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for DEFPUSHBUTTON is BS_DEFPUSHBUTTON and 
WS_TABSTOP. 


The following example demonstrates the correct usage of the DEFPUSH- 
BUTTON statement: 


DEFPUSHBUTTON "ON", 7, 18, 19, 20, 10 


RADIOBUTTON Statement 


Syntax 
RADIOBUTTON text, id, x, y, width, height, [[style]] 


This statement defines a radio-button control belonging to the BUTTON class. It 

creates a small circle that has the given text displayed just to its right. The control 
highlights the button when the user clicks the mouse in it and sends a message to 

its parent window. The control removes the highlight and sends a message on the 
next click. 


The text field takes an ASCII string that specifies the text to be displayed. The 
string must be enclosed in double quotation marks. To add a mnemonic to the 
text string, place the ampersand (&) ahead of the letter that will be the mne- 
monic. To use the ampersand as a character in a string, insert two ampersands 
(&&). 


The id field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are 4 of the dialog base 
width unit; the vertical units are 18 of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 4 of the dialog base width unit; the height 
units are 1 of the dialog base height unit. 


The optional style field can contain any combination (or none) of the following 
styles: 
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a WS_TABSTOP 
= WS_GROUP 
= WS_DISABLED 


These styles are described in Table 8.1, “Window Styles.” 


In addition to these styles, the style field may contain any combination (or none) 
of the BUTTON-class styles described in Table 8.3, “Control Styles.” Styles can 
be combined using the bitwise OR operator. 


Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for RADIOBUTTON is BS_RADIOBUTTON and WS_TAB- 
STOP. 


The following example demonstrates the correct usage of the RADIOBUTTON 
statement: 


RADIOBUTTON "AM 101", 10, 10, 10, 40, 10 


EDITTEXT Statement 


Syntax 
EDITTEXT id, x, y, width, height, [[style]] 


This statement defines an EDIT control belonging to the EDIT class. It creates a 
rectangular region in which the user can enter and edit text. The control displays 
a cursor when the user clicks the mouse in it. The user can then use the keyboard 
to enter text or edit the existing text. Editing keys include the BACKSPACE and 
DELETE keys. The user can also use the mouse to select characters to be deleted, 
or to select the place to insert new characters. 


The id field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are 4 of the dialog base 
width unit; the vertical units are 1 of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 4 of the dialog base width unit; the height 
units are ¥8 of the dialog base height unit. 
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The optional style field can contain any combination (or none) of the following 
styles: 

= WS_TABSTOP 

a WS_GROUP 

= WS_VSCROLL 

a WS_HSCROLL 

a WS_DISABLED 


These styles are described in Table 8.1, “Window Styles.” 


In addition to these styles, the style field may contain any combination (or none) 
of the EDIT-class styles described in Table 8.3, “Control Styles.” Styles can be 
combined using the bitwise OR operator. The EDIT-class styles must not conflict 
with each other. 


Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for EDITTEXT is WS_TABSTOP, ES_LEFT, and 
WS_BORDER. 


Keyboard use is predefined for edit controls. Predefined keys are listed in the Sys- 
tem Application Architecture, Common User Access: Advanced Interface Design 
Guide. 


The following example demonstrates the correct usage of the EDITTEXT 
statement: 


EDITTEXT 3, 10, 10, 100, 19 


COMBOBOX Statement 


Syntax 
COMBOBOX id, x, y, width, height, [[style]] 


This statement defines a combo box belonging to the COMBOBOX class. A 
combo box consists of either a static text field or edit field combined with a list 
box. The list box can be displayed at all times or pulled down by the user. If the 
combo box contains a static text field, the text field always displays the selection 
(if any) in the list-box portion of the combo box. If it uses an edit field, the user 
can type in the desired selection; the list box highlights the first item (if any) 
which matches what the user has entered in the edit field. The user can then 
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select the item highlighted in the list box to complete the choice. In addition, the 
combo box can be owner-draw and of fixed or variable height. 


The id field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are 14 of the dialog base 
width unit; the vertical units are 1 of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBase Units function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 4 of the dialog base width unit; the height 
units are 8 of the dialog base height unit. 


The optional style field can contain any combination (or none) of the following 
styles: 

a WS_TABSTOP 

= WS_GROUP 

g WS_VSCROLL 

=m WS_DISABLED 


These styles are described in Table 8.1, “Window Styles.” 


In addition to these styles, the style field may contain any combination (or none) 
of the combo-box styles described in Table 8.3, “Control Styles.” Styles can be 
combined using the bitwise OR operator. 


Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for COMBOBOX is WS_TABSTOP and CBS_SIMPLE. 


For information on the recommended keys for use in combo-box controls, see the 
System Application Architecture, Common User Access: Advanced Interface De- 
sign Guide. 


The following example demonstrates the correct usage of the COMBOBOX 
statement: 


COMBOBOX 777, 10, 19, 50, 54, CBS_SIMPLE | WS_VSCROLL | WS_TABSTOP 
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ICON Statement 


Syntax 
ICON text, id, x, y, width, height, [[style]] 


This statement defines an icon control belonging to the STATIC class. It creates 
an icon displayed in the dialog box. 


The text field specifies the name of an icon (not a filename) defined elsewhere in 
the resource file. 


The id field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are 4 of the dialog base 
width unit; the vertical units are 1 of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


For the ICON statement, the width and height fields are ignored; the icon auto- 
matically sizes itself. 


The optional style field allows only the SS_ICON style. 


Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for ICON is SS_ICON. 
The following example demonstrates the correct usage of the ICON statement: 


ICON "myicon" 981, 30, 30 


SCROLLBAR Statement 


Syntax 
SCROLLBAR id, x, y, width, height, [[style]] 


This statement defines a scroll-bar control belonging to the SCROLLBAR class. 
It is a rectangle that contains a scroll thumb and has direction arrows at both 
ends. The scroll-bar control sends a notification message to its parent whenever 
the user clicks the mouse in the control. The parent is responsible for updating 
the thumb position. Scroll-bar controls can be positioned anywhere in a window 
and used whenever needed to provide scrolling input. 


The id field takes a unique integer value that identifies the control. 
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The x and y fields take integer values that specify the location of the upper-left 
comer of the control in dialog units relative to the origin of the dialog box. The 
horizontal units are 1/4 of the dialog base width unit; the vertical units are 18 of 
the dialog base height unit. The current dialog base units are computed from the 
height and width of the current system font. The GetDialogBaseUnits function 
returns the dialog base units in pixels. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 4 of the dialog base width unit; the height 
units are 1 of the dialog base height unit. 


The optional style field can contain any combination (or none) of the following 
styles: 


= WS_TABSTOP 
= WS_GROUP 
a WS_DISABLED 


These styles are described in Table 8.1, “Window Styles.” 


In addition to these styles, the style field may contain any combination (or none) 
of the SCROLLBAR-class styles described in Table 8.3, “Control Styles.” Styles 
can be combined using the bitwise OR operator. 


Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for SCROLLBAR is SBS_HORZ. 


The following example demonstrates the correct usage of the SCROLLBAR 
statement: 


SCROLLBAR 999, 25, 30, 10, 100 


CONTROL Statement 


Syntax 
CONTROL text, id, class, style, x, y, width, height 
This statement defines a user-defined control window. 


The text field takes an ASCII string that specifies the text to be displayed. The 
string must be enclosed in double quotation marks. 


The id field takes a unique integer value that identifies the control. 
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The class field takes a predefined name, character string, or integer value that de- 
fines the class. This can be any one of the control classes; for a list of the control 
classes, see Table 8.2, “Control Classes.” If the value is a predefined name sup- 
plied by the application, it must be an ASCII string enclosed in double quotation 
marks. 


The style field takes a predefined name or integer value that specifies the style of 
the given control. The exact meaning of style depends on the class value. Tables 
8.2, “Control Classes,” and 8.3, “Control Styles,” list the control classes and 
corresponding styles. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are 4 of the dialog base 
width unit; the vertical units are 18 of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 4 of the dialog base width unit; the height 
units are 1 of the dialog base height unit. 


Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


Table 8.2 describes the six control classes: 


Table 8.2 Control Classes 


Class Description 


BUTTON A button control is a small rectangular child window that repre- 
sents a “button” that the user can turn on or off by clicking it 
with the mouse. Button controls can be used alone or in groups, 
and can either be labeled or appear without text. Button con- 
trols typically change appearance when the user clicks them. 


COMBOBOX Combo-box controls consist of a selection field similar to an 
edit control plus a list box. The list box may be displayed at all 
times or may be dropped down when the user selects a “pop 
box” next to the selection field. 


Depending on the style of the combo box, the user can or can- 
not edit the contents of the selection field. If the list box is 
visible, typing characters into the selection box will cause the 
first list box entry which matches the characters typed to be 
highlighted. Conversely, selecting an item in the list box dis- 
plays the selected text in the selection field. 
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Table 8.2 


Control Classes (continued) 


Class 


Description 


EDIT 


LISTBOX 


SCROLLBAR 


STATIC 


An edit control is a rectangular child window in which the user 
can enter text from the keyboard. The user selects the control, 
and gives it the input focus, by clicking the mouse inside it or 
pressing the TAB key. The user can enter text when the control 
displays a flashing caret. The mouse can be used to move the 
cursor and select characters to be replaced, or to position the 
cursor for inserting characters. The BACKSPACE key can be used 
to delete characters. 


Edit controls use the fixed-pitch font and display ANSI 
characters. They expand tab characters into as many space 
characters as are required to move the cursor to the next tab 
stop. Tab stops are assumed to be at every eighth character posi- 
tion. 


List-box controls consist of a list of character strings. The con- 
trol is used whenever an application needs to present a list of 
names, such as filenames, that the user can view and select. The 
user can select a string by pointing to the string with the mouse 
and clicking a mouse button. When a string is selected, it is 
highlighted, and a notification message is passed to the parent 
window. A scroll bar can be used with a list-box control to 
scroll lists that are too long or too wide for the control window. 


A scroll-bar control is a rectangle that contains a scroll thumb 
and has direction arrows at both ends. The scroll bar sends a 
notification message to its parent whenever the user clicks the 
mouse in the control. The parent is responsible for updating the 
thumb position, if necessary. Scroll-bar controls have the same 
appearance and function as the scroll bars used in ordinary 
windows. But unlike scroll bars, scroll-bar controls can be posi- 
tioned anywhere within a window and used whenever needed to 
provide scrolling input for a window. 


The scroll-bar class also includes size-box controls. A size-box 
control is a small rectangle that the user can expand to change 
the size of the window. 


Static controls are simple text fields, boxes, and rectangles that 
can be used to label, box, or separate other controls. Static con- 
trols take no input and provide no output. 
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Table 8.3 describes the control styles for each of the control classes: 


Table8.3 Control Styles 


Style Description 
BUTTON Class 
BS_PUSHBUTTON A small elliptical button containing 


the given text. The control sends a 
message to its parent whenever the 
user clicks the mouse inside the 
rectangle. 


BS_DEFPUSHBUTTON A small elliptical button with a bold 
border. This button represents the 
default user response. Any text is 
displayed within the button. 
Windows sends a message to the 
parent window when the user clicks 
the mouse in this button. 


BS_CHECKBOX A small rectangular button that can 
be checked; its border becomes 
bold when the user clicks the mouse 
in it. Any text appears to the right of 
the button. 


BS_AUTOCHECKBOX Identical to BS_CHECKBOX ex- 
cept that the button automatically 
toggles its state whenever the user 
clicks it. 


BS_RADIOBUTTON A small circular button whose 
border becomes bold when the user 
clicks the mouse in it. In addition, 
to make the border bold, Windows 
sends a message to the button’s 
parent notifying it that a click oc- 
curred. On the next click, Windows 
makes the border normal again and 
sends another message. 


BS_AUTORADIOBUTTON Identical to BS_RADIOBUTTON 
except that when the button is 
checked, the application is notified 
with BN_CLICKED, and all other 
radio buttons in the group are un- 
checked. 


BS_LEFTTEXT Text appears on the left side of the 
radio button or check-box button. 
Use this style with BS_CHECK- 
BOX, BS_3STATE, or 
BS_RADIOBUTTON styles. 
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Table 8.3. Control Styles (continued) 


Style 


Description 


BS_3STATE 


BS_AUTO3STATE 


BS_GROUPBOX 


BS_OWNERDRAW 


Identical to BS_CHECKBOX ex- 
cept that a button can be grayed as 
well as checked or unchecked. The 
grayed state is typically used to 
show that a check box has been dis- 
abled. 


Identical to BS_3STATE except that 
the button automatically toggles its 
state when the user clicks it. 


A rectangle into which other but- 
tons are grouped. Any text is 
displayed in the rectangle’s upper- 
left corner. 


An owner-draw button. The parent 
window is notified when the button 
is clicked. Notification includes a re- 
quest to paint, invert, and disable 
the button. 


COMBOBOX Class 


CBS_SIMPLE 


CBS_DROPDOWN 


CBS_DROPDOWNLIST 


CBS_OWNERDRAWFIXKED 


CBS_OWNERDRAWVARIABLE 


Displays the list box at all times. 
The current selection in the list box 
is displayed in the edit control. 


Is similar to CBS_SIMPLE, except 
that the list box is not displayed un- 
less the user selects an icon next to 

the selection field. 


Is similar to CBS_DROPDOWN, 
except that the edit control is re- 
placed by a static text item which 
displays the current selection in the 
list box. 


Specifies a fixed-height owner-draw 
combo box. The owner of the list 
box is responsible for drawing its 
contents; the items in the list box 
are all the same height. 


Specifies a variable-height owner- 
draw combo box. The owner of the 
list box is responsible for drawing 
its contents; the items in the list box 
can have different heights. 


Table 8.3 Control Styles (continued) 
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Style 


Description 


CBS_AUTOHSCROLL 


CBS_SORT 


CBS_HASSTRINGS 


CBS_OEMCONVERT 


Scrolls the text in the edit control to 
the right when the user types a 
character at the end of the line. If 
this style is not set, only text which 
fits within the rectangular boundary 
is allowed. 


Sorts strings entered into the list 
box. 


Specifies an owner-draw combo 
box that contains items consisting 
of strings. The combo box main- 
tains the memory and pointers for 
the strings so that the application 
can use the LB_GETTEXT 
message to retrieve the text for a 
particular item. 


Text entered in the combo box edit 
control is converted from the ANSI 
character set to the OEM character 
set and then back to ANSI. This en- 
sures proper character conversion 
when the application calls the Ansi- 
ToOem function to convert an 
ANSI string in the combo box to 
OEM characters. This style is most 
useful for combo boxes that contain 
filenames and applies only to 
combo boxes created with the 
CBS_SIMPLE or CBS_DROP- 
DOWN styles. 


EDIT Class 

ES_LEFT Flush-left text. 

ES_CENTER Centered text. This style is valid in 
multiline edit controls only. 

ES_RIGHT Flush-right text. This style is valid 


ES_LOWERCASE 


in multiline edit controls only. 


Lowercase edit control. An edit con- 
trol with this style converts all 
characters to lowercase as they are 
typed into the edit control. 
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Table 8.3 


Control Styles (continued) 


Style 


Description 


ES_UPPERCASE 


ES_PASSWORD 


ES_MULTILINE 


Uppercase edit control. An edit con- 
trol with this style converts all 
characters to uppercase as they are 
typed into the edit control. 


Password edit control. An edit con- 
trol with this style displays all 
characters as an asterisk (*) as they 
are typed into the edit control. An 
application can use the 
EM_SETPASSWORDCHAR 
message to change the character 
that is displayed. 


Multiple-line edit control. (The 
default is single-line.) If the 
ES_AUTOVSCROLL style is 
specified, the edit control shows as 
many lines as possible and scrolls 
vertically when the user presses the 
ENTER key. (This is actually the car- 
riage-return character, which the 
edit control expands to a carriage- 
return/line-feed combination. A line 
feed is not treated the same as a car- 
riage return.) If 
ES_AUTOVSCROLL is not given, 
the edit control shows as many lines 
as possible and beeps if the user 
presses ENTER when no more lines 
can be displayed. 


If the ES_AUTOHSCROLL style is 
specified, the multiple-line edit con- 
trol automatically scrolls 
horizontally when the caret goes 
past the right edge of the control. To 
start a new line, the user must press 
the ENTER key. If ES_AUTO- 
HSCROLL is not given, the control 
automatically wraps words to the 
beginning of the next line when nec- 
essary; a new line is also started if 
the user presses ENTER. The position 
of the wordwrap is determined by 
the window size. If the window size 
changes, the wordwrap position 
changes, and the text is redisplayed. 
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Table 8.3 Control Styles (continued) 


Style Description 


Multiple-line edit controls can have 
scroll bars. An edit control with 
scroll bars processes its own scroll- 
bar messages. Edit controls without 
scroll bars scroll as described 
above, and process any scroll mes- 
sages sent by the parent window. 


ES_AUTOVSCROLL Text is automatically scrolled up 
one page when the user presses the 
ENTER key on the last line. 


ES_AUTOHSCROLL Text is automatically scrolled to the 
right by 10 characters when the user 
types a character at the end of the 
line. When the user presses the 
ENTER key, the control scrolls all 
text back to position 0. 


ES_NOHIDESEL Normally, an edit control hides the 
selection when the control loses the 
input focus, and inverts the selec- 
tion when the control receives the 
input focus. Specifying ES_NO- 
HIDESEL overrides this default 
action. 


ES_OEMCONVERT Text entered in the edit control is 
converted from the ANSI character 
set to the OEM character set and 
then back to ANSI. This ensures 
proper character conversion when 
the application calls the Ansi- 
ToOem function to convert an 
ANSI string in the edit control to 
OEM characters. This style is most 
useful for edit controls that contain 
filenames. 


LISTBOX Class 


LBS_STANDARD Strings in the list box are sorted al- 
phabetically and the parent window 
receives an input message when- 
ever the user clicks or double-clicks 
a string. The list box contains 
borders on all sides. 
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Table 8.3. Control Styles (continued) 


Style Description 


LBS_EXTENDEDSEL The user can select multiple items 
using the mouse with the SHIFT 
and/or the CONTROL key or special 
key combinations. 


LBS_HASSTRINGS An owner-draw list box contains 
items consisting of strings. The list 
box maintains the memory and 
pointers for the strings so the appli- 
cation can use the LB_GETTEXT 
message to retrieve the text for a 
particular item. 


LBS_NOTIFY The parent receives an input 
message whenever the user clicks 
or double-clicks a string. 


LBS_MULTIPLESEL The string selection is toggled each 
time the user clicks or double-clicks 
the string. Any number of strings 
can be selected. 


LBS_MULTICOLUMN The list box contains multiple 
columns. The list box can be 
scrolled horizontally. The LB_SET- 
COLUMNWIDTH message sets the 
width of the columns. 


LBS_NOINTEGRALHEIGHT The size of the list box is exactly 
the size specified by the application 
when it created the list box. Nor- 
mally, Windows sizes a list box so 
that the list box does not display 
partial items. 


LBS_SORT The strings in the list box are sorted 
alphabetically. 
LBS_NOREDRAW The list-box display is not updated 


when changes are made. This style 
can be changed at any time by send- 
ing a WM_SETREDRAW message. 

LBS_OWNERDRAWFIXED The owner of the list box is re- 
sponsible for drawing its contents; 
the items in the list box are all the 
same height. 

LBS_OWNERDRAWVARIABLE The owner of the list box is re- 
sponsible for drawing its contents; 
the items in the list box are variable 
in height. 
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Table 8.3 Control Styles (continued) 
Style Description 


LBS_USETABSTOPS The list box is able to recognize and 
expand tab characters when draw- 
ing its strings. The default tab 
positions are set at every 32 dialog 
units. (A dialog unit is a horizontal 
or vertical distance. One horizontal 
dialog unit is equal to 4 of the cur- 
rent dialog base width unit. The 
dialog base units are computed 
from the height and width of the cur- 
rent system font. The 
GetDialogBaseUnits function re- 
turns the size of the dialog base 
units in pixels.) 


LBS_WANTKEYBOARDINPUT The owner of the list box receives 
WM_VKEYTOITEM or 
WM_CHARTOITEM messages 
whenever the user presses a key 
when the list box has input focus. 
This allows an application to per- 
form special processing on the 
keyboard input. 


SCROLLBAR Class 


SBS_VERT Vertical scroll bar. If neither 
SBS_RIGHTALIGN nor SBS_LEF- 
TALIGN is specified, the scroll bar 
has the height, width, and position 
given in the CreateWindow func- 
tion. 


SBS_RIGHTALIGN Used with SBS_VERT. The right 
edge of the scroll bar is aligned 
with the right edge of the rectangle 
specified by the x, y, width, and 
height values given in the 
Create Window function. The 
scroll bar has the default width for 
system scroll bars. 


SBS_LEFTALIGN Used with SBS_VERT. The left 
edge of the scroll bar is aligned 
with the left edge of the rectangle 
specified by the x, y, width, and 
height values given in the 
CreateWindow function. The 
scroll bar has the default width for 
system scroll bars. 
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Table 8.3. Control Styles (continued) 


Style Description 


SBS_HORZ Horizontal scroll bar. If neither 
SBS_BOTTOMALIGN nor 
SBS_TOPALIGN is specified, the 
scroll bar has the height, width, and 
position given in the CreateWin- 
dow function. 


SBS_TOPALIGN Used with SBS_HORZ. The top 
edge of the scroll bar is aligned 
with the top edge of the rectangle 
specified by the x, y, width, and 
height values given in the 
CreateWindow function. The 
scroll bar has the default height for 
system scroll bars. 


SBS_BOTTOMALIGN Used with SBS_HORZ. The bottom 
edge of the scroll bar is aligned 
with the bottom edge of the 
rectangle specified by the x, y, 
width, and height values given in 
the CreateWindow function. The 
scroll bar has the default height for 
system scroll bars. 


SBS_SIZEBOX Size box. If neither SBS_SIZEBOX- 
BOTTOMRIGHTALIGN nor 
SBS_SIZEBOXTOPLEFTALIGN 
is specified, the size box has the 
height, width, and position given in 
the CreateWindow function. 


SBS_SIZEBOXTOPLEFTALIGN Used with SBS_SIZEBOX. The top- 
left corner of the size box is aligned 
with the top-left corner of the 
rectangle specified by the x, y, 
width, and height values given in 
the CreateWindow function. The 
size box has the default size for sys- 
tem size boxes. 


SBS_SIZEBOXBOTTOMRIGHTALIGN Used with SBS_SIZEBOX. The bot- 
tom-right comer of the size box is 
aligned with the bottom-right corner 
of the rectangle specified by the x, 
y, width, and height values given in 
the CreateWindow function. The 
size box has the default size for sys- 
tem size boxes. 


Table8.3. Control Styles (continued) 


Style 
STATIC Class 


SS_LEFT 


SS_CENTER 


SS_RIGHT 


SS_LEFTNOWORDWRAP 


SS_SIMPLE 
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Description 


A simple rectangle displaying the 
given text flush left in the rectangle. 
The text is formatted before it is dis- 
played. Words that would extend 
past the end of a line are automati- 
cally wrapped to the beginning of 
the next line. 


A simple rectangle displaying the 
given text centered in the rectangle. 
The text is formatted before it is dis- 
played. Words that would extend 
past the end of a line are automati- 
cally wrapped to the beginning of 
the next line. 


A simple rectangle displaying the 
given text flush right in the 
rectangle. The text is formatted 
before it is displayed. Words that 
would extend past the end of a line 
are automatically wrapped to the 
beginning of the next line. 


A simple rectangle displaying the 
given text flush left in the rectangle. 
Tabs are expanded, but words are 
not wrapped. Text that extends past 
the end of a line is clipped. 


Designates a simple rectangle and 
displays a single line of text flush- 
left in the rectangle. The line of text 
cannot be shortened or altered in 
any way. (The control’s parent 
window or dialog box must not 
process the WM_CTLCOLOR 
message.) 
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Table 8.3 Control Styles (continued) 
Style 


SS_NOPREFIX 


SS_ICON 


SS_BLACKRECT 


SS_GRAYRECT 


SS_WHITERECT 


SS_BLACKFRAME 


Description 


Unless this style is specified, 
windows will interpret any “&” 
characters in the control’s text to be 
accelerator prefix characters. In this 
case, the “&” is removed and the 
next character in the string is under- 
lined. If a static control is to contain 
text where this feature is not 
wanted, SS_NOPREFIX may be 
added. This static-control style may 
be included with any of the defined 
static controls. 


You can combine SS_NOPREFIX 
with other styles by using the 
bitwise OR operator. This is most 
often used when filenames or other 
strings that may contain an “&” 
need to be displayed in a static con- 
trol in a dialog box. 


An icon displayed in the dialog box. 
The given text is the name of an 
icon (not a filename) defined else- 
where in the resource file. For the 
ICON statement, the width and 
height parameters in the 
CreateWindow function are ig- 
nored; the icon automatically sizes 
itself. 


Arectangle filled with the color 
used to draw window frames. This 
color is black in the default 
Windows color scheme. 


A rectangle filled with the color 
used to fill the screen background. 
This color is gray in the default 
Windows color scheme. 


A rectangle filled with the color 
used to fill window backgrounds. 
This color is white in the default 
Windows color scheme. 


Box with a frame drawn with the 
same color as window frames. This 
color is black in the default 
Windows color scheme. 
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8.8 Directives 


Table8.3 Control Styles (continued) 


Style Description 


SS_GRAYFRAME Box with a frame drawn with the 
same color as the screen back- 
ground (desktop). This color is gray 
in the default Windows color 
scheme. 

SS_WHITEFRAME Box with a frame drawn with the 
same color as window backgrounds. 
This color is white in the default 
Windows color scheme. 


SS_USERITEM User-defined item. 


The resource directives are special statements that define actions to be performed 
on the script file before it is compiled. The directives can assign values to names, 
include the contents of files, and control compilation of the script file. 


The resource directives are identical to the directives used in the C programming 
language. They are fully defined in the Microsoft C Language Reference. 


8.8.1 #include Statement 


Syntax 


#include filename 


This directive copies the contents of the file specified by filename into your 
resource script before the Resource Compiler processes the script. It replaces the 
reinclude directive of versions prior to Windows 3.0. 


The filename field is an ASCII string that specifies the DOS filename of the file 
to be included, using the same syntax as the C-language preprocessor #include 
directive. A forward slash (/) can be used instead of a backslash (for example, 
“root/sub”). If the filename has the .H or .C extension, only the preprocessor 
directives in the file are processed. Otherwise, this directive processes the entire 
contents of the file. 
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The following example demonstrates the correct usage of the #include statement: 


#include "WINDOWS.H" 


PenSelect MENU 
BEGIN 

Menuitem "&Black pen", BLACK_PEN 
END 


8.8.2 #define Statement 
Syntax 


#define name value 


This directive assigns the given value to name. All subsequent occurrences of 
name are replaced by value. 


The value field takes any integer value, character string, or line of text. 


The following example demonstrates the correct usage of the #define statement: 


dtdefine nonzero 1 

d#tdefine USERCLASS "MyControlClass" 
8.8.3 #undef Statement 

Syntax 

#undef name 


This directive removes the current definition of name. All subsequent occur- 
rences of name are processed without replacement. 


The following example demonstrates the correct usage of the #undef statement: 


ftundef nonzero 

dtundef USERCLASS 
8.8.4 #ifdef Statement 

Syntax 


#ifdef name 


This directive carries out conditional compilation of the resource file by checking 
the specified name. If name has been defined using a #define directive, #ifdef 
directs the Resource Compiler to continue with the statement immediately after 
#ifdef. If name has not been defined, #ifdef directs the compiler to skip all state- 
ments up to the next #endif directive. 
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Thr following example demonstrates the correct usage of the #ifdef statement: 


f#ifdef Debug 
errbox BITMAP errbox.bmp 
dtendif 


8.8.5 #itndef Statement 


Syntax 
#ifndef name 


This directive carries out conditional compilation of the resource file by checking 
the specified name. If name has not been defined or if its definition has been re- 
moved using the #undef directive, #ifndef directs the Resource Compiler to con- 
tinue processing statements up to the next #endif, #else, or #elif directive, and 
then to skip to the statement after #endif. If name is defined, #ifndef directs the 
compiler to skip to the next #endif, #else, or #elif directive. 


The following example demonstrates the correct usage of the #ifndef statement: 


ifndef Optimize 
errbox BITMAP errbox.bmp 
dtendif 


8.8.6 #if Statement 
Syntax 


#if constant-expression 


This directive carries out conditional compilation of the resource file by checking 
the specified constant-expression. If constant-expression is nonzero, #if directs 
the Resource Compiler to continue processing statements up to the next #endif, 
#else, or #elif directive, then skip to the statement after #endif. If constant-ex- 
pression is zero, #if directs the compiler to skip to the next #endif, #else, or #elif 
directive. 


The constant-expression field specifies a defined name, an integer constant, or an 
expression consisting of names, integers, and arithmetical and relational opera- 
tors. 


The following example demonstrates the correct usage of the #if statement: 


dif Version<3 
errbox BITMAP errbox.bmp 
dtendif 
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8.8.7 #elif Statement 
Syntax 


#elif constant-expression 


This directive marks an optional clause of a conditional compilation block de- 
fined by an #ifdef, #ifndef, or #if directive. The #elif directive carries out condi- 
tional compilation of the resource file by checking the specified constant- 
expression. If constant-expression is nonzero, #elif directs the Resource Com- 
piler to continue processing statements up to the next #endif, #else, or #elif direc- 
tive, then skip to the statement after #endif. If constant-expression is zero, #elif 
directs the compiler to skip to the next #endif, #else, or #elif directive. Any num- 
ber of #elif directives can be used in a conditional block. 


The constant-expression field specifies a defined name, an integer constant, or an 
expression consisting of names, integers, and arithmetical and relational opera- 
tors. 


The following demonstrates the correct usage of the #elif statement: 


#Hif Version<3 

errbox BITMAP errbox.bmp 
#telif Version<7 

errbox BITMAP userbox.bmp 
#tendif 


8.8.8 #else Statement 
Syntax 


#else 


This directive marks an optional clause of a conditional compilation block de- 
fined by an #ifdef, #ifndef, or #if directive. The #else directive must be the last 
directive before #endif. 


The following example demonstrates the correct usage of the #else statement: 


ifdef Debug 

errbox BITMAP errbox.bmp 
itelse 

errbox BITMAP userbox.bmp 
itendif 
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8.8.9 #endif Statement 


8.9 Summary 


Syntax 
#endif 


This directive marks the end of a conditional compilation block defined by an #if 
or #ifdef directive. One #if or #endif is required for each #ifdef directive. 


The resource script statements define resources that the Resource Compiler adds 
to an application’s executable file. The application can then load these resources 
as they are needed at run time. For more information on topics related to the 
Resource Compiler, see the following: 


Topic Reference 

General information on Guide to Programming: Chapter 1, “An 

Windows programming Overview of the Windows Environment” 

Menus Guide to Programming: Chapter 7, “Menus” 

Controls and dialog boxes Guide to Programming: Chapter 8, 
“Controls,” and Chapter 9, “Dialog Boxes” 

Using the Resource Tools: Chapter 3, “Compiling Resources: 

Compiler The Resource Compiler” 

Designing dialog boxes Tools: Chapter 5, “Designing Dialog Boxes: 


The Dialog Editor” 
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This chapter describes the file formats used to create, execute, and supply data to 
Microsoft Windows applications. These files include the following: 


= Bitmap files 

= Icon resource files 

= Cursor resource files 
= Clipboard files 


= Metafiles 


9.1 Bitmap File Formats 


Windows version 3.0 bitmap files store a bitmap in a device-independent format 
which allows Windows to display the bitmap on any device. In this case, the term 
“device independent” means that the bitmap specifies pixel color in a form inde- 
pendent of the method used by any particular device to represent color. The as- 
sumed file extension of a Windows device-independent bitmap file is BMP. 


Each bitmap file contains a BITMAPFILEHEADER data structure immedi- 
ately followed by a single, device-independent bitmap (DIB) consisting of a 
BITMAPINFO data structure and an array of bytes that defines the bitmap bits. 


Windows version 3.0 also reads bitmap files in the format read by Microsoft 
OS/2 Presentation Manager version 1.2. These files consist of a BITMAPFILE- 
HEADER data structure immediately followed by a BITMAPCOREINFO data 
structure. Following this data structure is an array of bytes that defines the bit- 
map bits. 


See Chapter 7, “Data Types and Structures,” for information on the BITMAP- 
FILEHEADER, BITMAPCOREINFO and BITMAPINFO data structures. 
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9.2 Icon Resource File Format 


An icon resource file (with the .ICO file extension) can be device independent 
both for color and resolution. 


Icon resource files can contain multiple device-independent bitmaps defining the 
icon image, one for each targeted display-device resolution. Windows detects the 
resolution of the current display and matches it against the x and y pixel-size 
values specified for each version of the image. If Windows determines that there 
is an exact match between an icon image and the current device, then it uses the 
matching image; otherwise, it selects the closest match and stretches the image to 
the proper size. 


If an icon resource file contains more than one image for a particular resolution, 
Windows uses the icon image that most closely matches the color capabilities of 
the current display device. If no image exists which exactly matches the device 
capabilities, Windows selects the image which has the greatest number of colors 
without exceeding the number of display-device colors. If all images exceed the 
color capabilities of the current display device, then Windows uses the icon 
image with the least number of colors. 


The icon resource file contains a header structure at the beginning of the file 
which identifies the type and number of icon images contained in the file. The 
following shows the format of this header: 


Field Type/Description 

icoReserved WORD Is reserved and must be set to 0. 

icoResourceType WORD Specifies the type of resource contained 
in the file. For an icon resource, this field must be 1. 

icoResourceCount WORD Specifies the number of images contained 
in the file. 


The resource directory follows this header. The resource directory consists of one 
or more arrays of resource descriptors. The icoResorceCount specifies the num- 
ber of arrays. The following list shows the format of the array: 


Field Type/Description 

Width BYTE Specifies the width in pixels of this form 
of the icon image. Acceptable values are 16, 32, or 
64. 

Height BYTE Specifies the height in pixels of this form 


of the icon image. Acceptable values are 16, 32, or 
64. 
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Field Type/Description 

ColorCount BYTE Specifies the number of colors in this form 
of the icon image. Acceptable values are 2, 8, or 16. 

Reserved BYTE Reserved for future use. 

Reserved WORD Reserved for future use. 

Reserved WORD Reserved for future use. 

icoDIBSize DWORD Specifies in bytes the size of the pixel 
array for this form of the icon image. 

icoDIBOffset DWORD Specifies the offset in bytes from the 


beginning of the file to the device-independent bit- 
map for this form. 


Icons can be in color. To achieve transparency, the DIB for each icon will consist 
of two parts: 


1. The first part is a color bitmap which supplies the XOR mask for the icon. 


2. The second part is a monochrome bitmap which provides the AND mask that 
defines the transparent portion of the icon. 


The monochrome bitmap does not contain a DIB header, but instead immediately 
follows the color bitmap. It must have the same pixel height as the color bitmap. 


9.3 Cursor Resource File Format 


Like icon resource files, cursor resource files (with the .CUR file extension) may 
contain multiple images to match targeted display-device resolutions. In the case 
of cursors, Windows determines the best match for a particular display-device 
driver by examining the width and height of the cursor images. 


The cursor resource file contains a header structure at the beginning of the file 
which identifies the type and number of resources in the file. The following 
shows the format of this header: 


Field Type/Description 
curReserved WORD Is reserved and must be set to 0. 
curResourceType WORD _ Specifies the type of resource contained 


in the file. For a cursor resource, this field must be 2. 


curResourceCount WORD _ Specifies the number of resources con- 
tained in the file. 
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The resource directory follows this header. The resource directory consists of one 
or more arrays of resource descriptors. The curResorceCount specifies the num- 
ber of arrays. The following shows the format of the array: 


Field Type/Description 

curWidth BYTE Specifies the width in pixels of this form 
of the cursor image. 

cur Height BYTE Specifies the height in pixels of this form 
of the cursor image. 

ColorCount BYTE Specifies the number of colors in this form 
of the icon image. Acceptable values are 2, 8, or 16. 

Reserved BYTE Is reserved and must be set to 0. 

cur XHotspot WORD Specifies in pixels the horizontal position 
of the hotspot. 

curY Hotspot WORD Specifies in pixels the vertical position of 
the hotspot. 

curDIBSize DWORD Specifies in bytes the size of the pixel 


array for this form of the cursor image. 


curDIB Offset DWORD _ Specifies in bytes the offset to the 
device-independent bitmap for this form. The offset 
is from the beginning of the file. 


Cursors are monochrome. The bitmap for a cursor consists of two parts; the first 
half is the XOR mask specifying the visible image, and the second half is the 
AND mask specifying the transparent portion of the cursor image. The two parts 
must be of equal width and height. By combining the values in corresponding 
mask bits, Windows determines whether a pixel is black, white, inverted, or trans- 
parent. 


Table 9.1 shows what values are necessary to produce the corresponding colors, 
inversions, or transparencies: 


Table 9.1 Bit Mask Results 


Bit Value Bit Value Bit Value Bit Value 


AND mask 0 0 1 1 
XOR mask 0 1 0 1 
Resultant Pixel Black White Transparent Inverted 
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Figure 9.1 shows two bitmaps that represent the AND mask and the XOR mask 
for a cursor. The bit settings in the two bitmaps create a black, cross-shaped 


cursor: 


Resultant 
Cursor 


Figure 9.1 Settings and Resultant Cursor 


9.4 Clipboard File Format 


The Windows clipboard saves and reads clipboard data in files with the .CLP ex- 
tension. A clipboard-data file contains a value that identifies it as a clipboard- 
data file, one or more data structures defining the format, size, and location of the 
clipboard data, and one or more blocks of the actual data. 


The clipboard-data file begins with a header consisting of two fields. The follow- 
ing describes these fields: 
Field Type/Description 


Fileldentifier WORD Identifies the file as a clipboard-data file. 
This field must be set to CLP_ID. 


FormatCount WORD Specifies the number of clipboard for- 
mats contained in the file. 


This header is followed by one or more data structures, each of which identifies 
the format, size, and offset of a block of clipboard data. The following shows the 
fields of this data structure: 


Field Type/Description 


FormatID WORD Specifies the clipboard-format ID of the 
clipboard data. See the description of the SetClip- 
boardData function in Chapter 4, “Functions 
Directory,” in Reference, Volume 1, for information 
on clipboard formats. 


LenData DWORD Specifies in bytes the length of the clip- 
board data. 
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Field Type/Description 

OffData DWORD Specifies in bytes the offset of the clip- 
board-data block. The offset is from the beginning 
of the file. 

Name Is a 79-character array that specifies the format 


name for a private clipboard format. 


The first block of clipboard data follows the last of these structures. For bitmaps 
and metafiles, the bits follow immediately after the bitmap header and the 
METAFILEPICT data structures. 


9.5 Metafile Format 


A metafile consists of a collection of graphics device interface (GDI) function 
calls that create specific images on a device. Metafiles provide convenient 
storage for images that appear repeatedly in applications, and also allow you to 
use the clipboard to cut and paste images from one application to another. 


Metafiles store images as a series of GDI function calls. After storing the func- 
tion calls, applications play a metafile to generate an image on a device. 


When an object is created during playback, GDI adds the handle of the object to 
the first available entry in the metafile handle table. GDI clears the table entry 
corresponding to the object when it is deleted during playback, allowing the table 
entry to be reused when another object is created. 


NOTE Functions described in this section are discussed in greater detail in Chapter 4, 
“Functions Directory,” in Reference, Volume 1. 


The metafile itself consists of two parts: a header and a list of records. The 
header contains a description of the size (in words) of the metafile and the num- 
ber of drawing objects it uses. The list of records contains the GDI functions. The 
drawing objects can be pens, brushes, or bitmaps. 


9.5.1 Metafile Header 


The following structured list shows the format of the metafile header: 


struct { 

WORD mtType; 

WORD mtHeaderSize; 
WORD mtVersion; 
DWORD mtSize; 

WORD mtNoObjects; 
DWORD mtMaxRecord; 
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WORD mtNoParameters; 
} 


The metafile header contains the following fields: 


Field Description 


mtType Specifies whether the metafile is in memory or re- 
corded in a disk file. It is one of these two values: 


Value Meaning 

1 Metafile is in memory 

2 Metafile is in a disk file 
mtHeaderSize Specifies the size in words of the metafile header. 
mtVersion Specifies the Windows version number. The ver- 

sion number for Windows version 3.0 is 0x300. 
mtSize Specifies the size in words of the file. 
mtNoObjects Specifies the maximum number of objects that 


exist in the metafile at the same time. 


mtMaxRecord Specifies the size in words of the largest record in 
the metafile. 


mtNoParameters Is not used. 


9.5.2 Metafile Records 


A series of records follows the metafile header. Metafile records describe GDI 
functions. GDI stores most of the GDI functions that an application can use to 
create metafiles in similar, typical records. “Typical Metafile Record,” later in 
this section, shows the format of the typical metafile record. Table 9.2, “GDI 
Functions and Values,” lists the functions which GDI records in typical records, 
along with their respective function numbers. 


The remainder of the functions contain more complex structures in their records. 
“Function-Specific Records,” later in this section, describes the records for these 
functions. 


In some cases, there are two versions of a metafile record. One version represents 
the record created by versions of Windows prior to version 3.0, while the second 
version represents the record created by Windows versions 3.0 and later. 
Windows 3.0 plays all metafile versions, but stores only 3.0 versions. Windows 
versions prior to 3.0 will not play metafiles recorded by Windows 3.0. 


9-8 Reference — Volume 2 
[SSIS RI NERS EIS RM SIS GSS os SEDC SIE Th oa AE SIRT FDS BLES PDS EID ELDEST SS ORSINI Ee AT REG ST VST Ee RTT TET ORENETRE CHIT ATOR REET TT OTS Eee 


Table 9.2 GDI Functions and Values 


Function Value 

Are 0x0817 
Chord 0x0830 
Ellipse 0x0418 
ExcludeClipRect 0x0415 
FloodFill 0x0419 
IntersectClipRect 0x0416 
LineTo 0x0213 
MoveTo 0x0214 
OffsetClipRgn 0x0220 
Offset ViewportOrg 0x0211 
OffsetWindowOrg 0x020F 
PatBit 0x061D 
Pie 0x081A 
RealizePalette (3.0 and later) 0x0035 
Rectangle 0x041B 
ResizePaleite (3.0 and later) 0x0139 
RestoreDC 0x0127 
RoundRect 0x061C 
SaveDC 0x001E 
ScaleViewportExt 0x0412 
ScaleWindowExt 0x0400 
SetBkColor 0x0201 
SetBkMode 0x0102 
SetMapMode 0x0103 
SetMapperFlags 0x0231 
SetPixel Ox041F 
SetPolyFillMode 0x0106 
SetROP2 0x0104 
SetStretchBltMode 0x0107 
SetTextAlign 0x012E 
SetTextCharExtra 0x0108 
SetTextColor 0x0209 
SetText Justification 0x020A 


SetViewportExt 0x020E 
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Table 9.2 GDI Functions and Values (continued) 


a OS eee 


Function Value 

SetViewportOrg 0x020D 
SetWindowExt 0x020C 
SetWindowOrg 0x020B 


Typical Metafile Record 


The following structured list shows the format of a typical metafile record: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParmC]; 

} 


A typical metafile record contains the following fields: 


Field Description 

rdSize Specifies the size in words of the record. 

rdFunction Specifies the function number. 

rdParn ] Is an array of words containing the function parameters, 
in the reverse order in which they are passed to the func- 
tion. 


Function-Specific Records 


Some metafile records contain data structures in the parameter field. This section 
contains definitions for these records. 


AnimatePalette Record 


The AnimatePalette record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm[]; 

} 


This record contains the following fields: 
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Field Description 

rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x0436. 

rdParn | Contains the following elements: 
Element Description 
start First entry to be animated. 
numentries Number of entries to be animated. 
entries PALETTEENTRY blocks. 


BitBit Record (Prior to 3.0) 


The BitBlt record stored by Windows versions prior to 3.0 contains a device-de- 
pendent bitmap which may not be suitable for playback on all devices. The fol- 
lowing is the format of this record: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm[]; 

} 


This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x0922 . 
rdParn] ] Contains the following elements: 
Element Description 
raster op High word of the raster opera- 
tion. 
SY The y-coordinate of the source 
origin. 
SX The x-coordinate of the source 
origin. 


DYE Destination y-extent. 
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Field Description 

Element Description 

DXE Destination x-extent. 

DY The y-coordinate of destina- 
tion origin. 

DX The x-coordinate of destina- 
tion origin. 

bmWidth Width of bitmap (in pixels) 

bmHeight Height of bitmap (in raster 
lines) 

bmWidthBytes Number of bytes in each raster 
line. 

bmPlanes Number of color planes in the 
bitmap. 

bmBitsPixel Number of adjacent color bits. 

bits Actual device-dependent bit- 


map bits. 


BitBit Record 


The BitBlt record stored by Windows versions 3.0 and later contains a device-in- 
dependent bitmap suitable for playback on any device. The following is the for- 
mat of this record: 


struct. -{ 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm(]; 

} 


This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x0940. 


rdParn{ ] Contains the following elements: 


9-12 Reference — Volume 2 
AS TS SE I ESE EE Ee ER I SE I TLS IGS OE FEET SEY 


Field Description 

Element Description 

raster op High word of the raster opera- 
tion. 

SY The y-coordinate of the source 
origin. 

SX The x-coordinate of the source 
origin. 

DYE The y-extent of the destination. 

DXE The x-extent of the destination. 

DY The y-coordinate of destina- 
tion origin. 

DX The x-coordinate of destina- 
tion origin. 

BitmapInfo BITMAPINFO data structure. 

bits Actual device-independent bit- 
map bits. 


CreateBrushindirect Record 
The CreateBrushIndirect record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
LOGBRUSH rdParm; 
} 


This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x02FC. 


rdParm Specifies the logical brush. 
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CreateFontindirect Record 
The CreateFontIndirect record has the following format: 


StTUCE 

DWORD rdSize; 
WORD rdFunction; 
LOGFONT rdParm; 
} 


This record contains the following fields: 


Field Description 

rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x02FB. 
rdParm Specifies the logical font. 


CreatePalette Record 


The CreatePalette record has the following format: 


struct { 

DWORD rdSize; 

WORD rdFunction; 
LOGPALETTE rdParm; 
} 


This record contains the following fields: 


Field Description 

rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x00F7. 
rdParm Specifies the logical palette. 


CreatePatternBrush Record (Prior to 3.0) 


The CreatePatternBrush record stored by Windows versions prior to 3.0 con- 
tains a device-dependent bitmap which may not be suitable for playback on all 
devices. The following is the format of this record: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm[]; 

} 
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This record contains the following fields: 


Field Description 

rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x01F9. 

rdParn] ] Contains the following elements: 
Element Description 
bmWidth Bitmap width. 
bmHeight Bitmap height. 
bmWidthBytes Bytes per raster line. 
bmPlanes Number of color planes. 
bmBitsPixel Number of adjacent color bits 

that define a pixel. 

bmBits Pointer to bit values. 
bits Actual bits of pattern. 


CreatePatternBrush Record 


The CreatePatternBrush record stored by Windows versions 3.0 and later con- 
tains a device-independent bitmap suitable for playback on all devices. The fol- 
lowing is the format of this record: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParmC]; 

} 


This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x0142. 


rdParn{ ] Contains the following elements: 
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Field Description 


Element Description 


type Bitmap type. This field may 
be either of these two values: 


a BS_PATTERN—Brush is 
defined by a device-de- 
pendent bitmap through a 
call to the CreatePat- 
ternBrush function. 


a BS_DIBPATTERN— 
Brush is defined by a 
device-independent bitmap 
through a call to the 
CreateDIBPatternBrush 
function. 


Usage Specifies whether the bmi- 
Colors[ ] field of the 
BITMAPINFO data structure 
contains explicit RGB values 
or indexes into the currently 
realized logical palette. This 
field must be one of the fol- 
lowing values: 


a DIB_RGB COLORS— 
The color table contains 
literal RGB values. 


a DIB_PAL_COLORS— 
The color table consists of 
an array of indexes into the 
currently realized logical 
palette. 


BitmapInfo BITMAPINFO data structure. 


bits Actual device-independent bit- 
map bits. 
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CreatePenIindirect Record 
The CreatePenIndirect record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
LOGPEN rdParm; 

} 


This record contains the following fields: 


Field Description 

rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x02FA. 
rdParm Specifies the logical pen. 

Create Region Record 


The Create Region record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm[]; 

} 


This record contains the following fields: 


Field Description 

rdSize Specifies the record size in words. 
rdFunction Specifies the function number Ox06FF. 
rdParn[ ] Specifies the region to be created. 


DeleteObject 


The DeleteObject record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm; 

} 


This record contains the following fields: 
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Field Description 

rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x01FO0. 

rdParm Specifies the handle-table index of the object to be 
deleted. 

DrawText Record 


The DrawText record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm[]; 

} 


This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x062F. 
rdParmf ] Contains the following elements: 
Element Description 
format Method of formatting. 
count Number of bytes in the string. 
rectangle Rectangular structure defining 
area where text is to be defined 
string Byte array containing the 
string. The array is 
((count + 1) >> 1) words long. 
Escape Record 


The Escape record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParml]; 

} 
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This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x0626. 
rdParn ] Contains the following elements: 
Element Description 
escape number Number identifying in- 
dividual escape. 
count Number of bytes of 
information. 
input data Variable length field. 
The field is 
((count+1)/ >> 1) 
words long. 
ExtTextOut Record 
The ExtTextOut record has the following format: 
struct { 
DWORD rdSize; 
WORD rdFunction; 
WORD rdParmC]; 
} 
This record contains the following fields: 
Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x0A32. 
rdParn ] Contains the following elements: 
Element Description 
y Logical y-value of string’s 
starting point. 
X Logical x-value of string’s 


starting point. 
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Field 


Polygon Record 


Description 

Element Description 

count Length of the string. 

options Rectangle type. 

rectangle RECT structure defining the 
ExtTextOut rectangle if op- 
tions element is nonzero; 
nonexistent if options element 
equals zero. 

string Byte array containing the 
string. The array is 
((count + 1) >> 1) words long. 

dxarray Optional word array of inter- 


character distances. 


The Polygon record has the following format: 


struct { 
DWORD rdSize; 


WORD rdFunction; 


WORD rdParm[]; 
} 


This record contains the following fields: 


Field 
rdSize 
rdFunction 


rdParn{ |] 


Description 
Specifies the record size in words. 
Specifies the function number 0x0324. 


Contains the following elements: 


Element Description 


count Number of points. 


list of points List of individual points. 
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PolyPolygon Record 


The PolyPolygon record has the following format: 
struct { 
DWORD rdSize; 


WORD rdFunction; 
WORD rdParm[]; 


This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x0538. 
rdParn] ] Contains the following elements: 
Element Description 
count Total number of points. 
list of polygon List of number of points for 
counts each polygon. 
list of points List of individual points. 
Polyline Record 


The Polyline record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParml]; 

} 


This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x0325. 


rdParn ] Contains the following elements: 
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Field Description 

Element Description 

count Number of points. 

list of points List of individual points. 
SelectClipRegion 


The SelectClipRegion record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm; 

} 


This record contains the following fields: 


Field Description 

rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x012C. 
rdParm Specifies the handle-table index of the region 


being selected. 


SelectObject 
The SelectObject record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm; 

} 


This record contains the following fields: 


Field Description 

rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x012D. 
rdParm Specifies the handle-table index of the object 


being selected. 
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SelectPalette Record 


The SelectPalette record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm; 

} 


This record contains the following fields: 


Field Description 

rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x0234. 
rdParm Specifies the handle-table index of the logical 


palette being selected. 


SetDIBitsToDevice Record 


The SetDIBitsToDevice record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm[]; 

} 


This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x0D33. 
rdParn ] Contains the following elements: 
Element Description 
wUsage Flag indicating whether the 


bitmap color table contains 
RGB values or indexes into 
the currently realized logical 
palette. 
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Field Description 

Element 5 Description 

numscans Number of scan lines in the 
bitmap. 

startscan First scan line in the bitmap. 

srcY The y-coordinate of the origin 
of the source in the bitmap. 

stcX The x-coordinate of the origin 
of the source in the bitmap. 

extY Height of the source in the bit- 
map. 

extX Width of the source in the bit- 
map. 

destY The y-coordinate of the origin 
of the destination rectangle. 

destX The x-coordinate of the origin 
of the destination rectangle. 

BitmapInfo BITMAPINFO data structure. 

bits Actual device-independent bit- 
map bits. 


SetPaletteEntries Record 


The SetPaletteEntries record has the following format: 


struct. { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParmC]; 

} 


This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x0037. 


rdParn ] Contains the following elements: 


9-24 Reference — Volume 2 


Field Description 
Element Description 
start First entry to be set in the 
palette. 
numentries Number of entries to be set in 
the palette. 
entries PALETTEENTRY blocks. 


StretchBlt Record (Prior to 3.0) 


The StretchBlt record stored by Windows versions prior to 3.0 contains a device- 
dependent bitmap which may not be suitable for playback on all devices. The fol- 
lowing is the format of this record: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm[]; 

} 


This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x0B23. 
rdParn ] Contains the following elements: 
Element Description 
raster op Low word of the raster opera- 
tion. 
raster op High word of the raster opera- 
tion. 
SYE The y-extent of the source. 
SXE The x-extent of the source. 
SY The y-coordinate of the source 


origin. 


Field 


Description 


Element 


SX 


DYE 
DXE 
DY 


DX 


bmWidth 
bmHeight 


bmWidthBytes 
bmPlanes 


bmBitsPixel 


bits 


StretchBit Record 


The StretchBlt record stored by Windows versions 3.0 and later contains a 
device-independent bitmap suitable for playback on all devices. The following is 
the format of this record: 


Ss 


} 


truct { 
DWORD rdSize; 


WORD rdFunction; 


WORD rdParm[]; 
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Description 


The x-coordinate of the source 
origin. 
The y-extent of the destination. 


The x-extent of the destination. 


The y-coordinate of destina- 
tion origin. 


The x-coordinate of destina- 
tion origin. 


Width of the bitmap in pixels. 


Height of the bitmap in raster 
lines. 


Number of bytes in each raster 
line. 


Number of color planes in the 
bitmap. 


Number of adjacent color bits. 


Actual bitmap bits. 
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This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x0B41. 
rdParn_ ] Contains the following elements: 
Element Description 
raster op Low word of the raster opera- 
tion. 
raster op High word of the raster opera- 
tion. 
SYE The y-extent of the source. 
SXE The x-extent of the source. 
SY The y-coordinate of the source 
origin. 
SX The x-coordinate of the source 
origin. 
DYE The y-extent of the destination. 
DXE The x-extent of the destination. 
DY The y-coordinate of destina- 
tion origin. 
DX The x-coordinate of destina- 
tion origin. 
BitmapInfo BITMAPINFO data structure. 
bits Actual device-independent bit- 
map bits. 


StretchDIBits Record 
The StretchDIBits record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm[]; 

} 
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This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number Ox0F43. 
rdParn{ | Contains the following elements: 
Element Description 
dwRop Raster operation to be per- 
formed. 
wUsage Flag indicating whether the 
bitmap color table contains 
RGB values or indexes into 
the currently realized logical 
palette. 
srcYExt Height of the source in the bit- 
map. 
srcXExt Width of the source in the bit- 
map. 
srcY The y-coordinate of the origin 
of the source in the bitmap. 
srcX The x-coordinate of the origin 
of the source in the bitmap. 
dst YExt Height of the destination 
rectangle. 
dstXExt Width of the destination 
rectangle. 
dstY The y-coordinate of the origin 
of the destination rectangle. 
dstX The x-coordinate of the origin 
of the destination rectangle. 
BitmapInfo BITMAPINFO data structure. 
bits Actual device-independent bit- 


map bits. 
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TextOut Record 


The TextOut record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm[]; 

} 


This record contains the following fields: 


Field Description 

rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x0521. 

rdParn{ ] Contains the following elements: 
Element Description 
count The string’s length. 
string The actual string. 
y-value Logical y-coordinate of 

string’s starting point. 

x-value Logical x-coordinate of 


string’s starting point. 


9.5.3 Sample Metafile Program Output 


This section shows the metafile created by a sample program. 


The following sample program creates a small metafile in which a purple 
rectangle with a green border is drawn, and the words “Hello People” are written 
in the rectangle. 


MakeAMetaFile(hDC) 


HDC hDC; 

{ 

HPEN hMetaGreenPen; 
HBRUSH hMetaVioletBrush; 
HDC hDCMeta; 


HANDLE  hMeta; 


/* create the metafile with output going to the disk 
*/ 
hDCMeta = CreateMetaFile( (LPSTR) "sample.met"); 
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hMetaGreenPen = CreatePen(G, @, (DWORD) OxOGOOFFOD); 
SelectObject(hDCMeta, hMetaGreenPen) ; 


hMetaVioletBrush = CreateSolidBrush( (DWORD) 
OxOOFFOOFF) ; 
SelectObject(hDCMeta, hMetaVioletBrush) ; 


Rectangle(hDCMeta, 9, @, 150, 70); 


TextOut(hDCMeta, 18, 10, (LPSTR) "Hello People", 12); 


/* we are done with the metafile */ 
= CloseMetaFile(hDCMeta); 


hMeta 


/* play the metafile that we just created */ 
PlayMetaFile(hDC, hMeta); 


} 


The resulting binary file SAMPLE.MET looks like this: 


8001 
Q009 
9190 
O0OO 
O0G2 
GOGO 
GOGO 


BOOB 
O2FA 
GOGO 


GOGO 
g12D 
0200 


G000 
O2FC 
BLOB 


BOBO 
g12D 
081 


OOOO 
O41B 
0046 


GOO0 
9521 


9836 


OBOC 


0608 


0080 


0004 


O0B7 


mtType... disk metafile 
MeESUZEs.... 

mtVersion 

mtSize 

mtNoObjects 

mtMaxRecord 
mtNoParameters 


rdSize 
rdFunction (CreatePen function call) 
Q000 OBOG FFOB® rdParm (LOGPEN structure defining pen) 


rdSize 
rdFunction (SelectObject) 
rdParm (index to object #@... the above pen) 


rdSize 
rdFunction (CreateBrush) 


OOFF OOFF @VG@G@ rdParm (LOGBRUSH structure defining the brush) 


0004 


0007 


0096 


QBOC 


rdParm 


rdSize 
rdFunction (SelectObject) 
rdParm (index to object #1... the brush) 


rdSize 
rdFunction (Rectangle) 
GQOO9 O2OB rdParm (parameters sent to Rectangle... 
in reverse order) 


rdSize 
rdFunction (TextOut) 
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BOBC count 

string 

48 65 6C 6C 6F 20 5@ 65 6F 70 6C 65 "Hello People" 
OOBA y-value 

QOBA x-value 


9.6 Summary 


Windows files store information required to create Windows applications as well 
as data needed by the Windows system and Windows applications during execu- 
tion. For more information on topics related to Windows files, see the following: 


Topic Reference 


Metafile functions Reference, Volume I: Chapter 1, “Window 
Manager Interface Functions,” and Chapter 
4, “Functions Directory” 


Device-independent bitmaps Guide to Programming: Chapter 11, 


“Bitmaps” 

Windows clipboard Guide to Programming: Chapter 13, “The 
Clipboard” 

Creating icons and cursors Tools: Chapter 4, “Designing Images: 


SDKPaint” 


Chapter 


10 


Module-Definition 
Statements 


This chapter describes the statements contained in the module-definition file 
that defines the application’s contents and system requirements for the LINK 
program. LINK links compiled source files with Microsoft Windows and other 
libraries to create an executable Windows application. For information on run- 
ning LINK, see Tools. 


The module-definition file contains one or more of the following module state- 
ments: 


Statement Description 

CODE Code-segment attributes 

DATA Data-segment attributes 
DESCRIPTION One-line description of the module 
EXETYPE .EXE header type (Windows or OS/2) 
EXPORTS Exported functions 

HEAPSIZE Size of local heap in bytes 
IMPORTS Imported functions 

LIBRARY Dynamic-link library name 
NAME Module name 

SEGMENTS Additional code segment 
STACKSIZE Size of local stack in bytes 

STUB Old-style executable 


This chapter describes these statements, their syntax, required and optional 
parameters, and usage. 


Comments 


Example 


DATA 
Syntax 
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CODE [FIXEDIMOVEABLE] [DISCARDABLE] [\PRELOADILOADONCALL] 


This statement defines the attributes of the standard code segment. The standard code seg- 
ment is the application segment having the name _TEXT and belonging to the class 
CODE. In C applications, the standard data segment is created automatically if no specific 
segment name is included in the C-Compiler command line. 


The FIXED option, if included, means that the segment remains at a fixed memory loca- 
tion; the MOVEABLE option means that the segment can be moved, if necessary, in order 
to compact memory. 


The DISCARDABLE option, if included, means that the segment can be discarded if it is 
no longer needed. 


The PRELOAD option, if included, means that the segment is loaded when the module is 
first loaded; the LOADONCALL option means that the segment is loaded when it is 
called. The Resource Compiler may override this option. See Tools for more information. 


There are no default attributes for code segments. The .DEF file should always explicitly 
define code-segment attributes. 


If conflicting options are included in the same statement, LINK uses the overriding option 
to determine the segment attributes. The following list shows which options override 
which: 

MOVEABLE overrides FIXED. 

PRELOAD overrides LOADONCALL. 


CODE MOVEABLE LOADONCALL 


In this example, the loader forces all fixed and moveable (but not discardable) data 
segments to be loaded. Libraries cannot have code that is moveable but not discardable. 


DATA [NONEISINGLEIMULTIPLE] [FIXEDIMOVEABLE] 


This statement defines the attributes of the standard data segment. The standard data seg- 
ment is all application segments belonging to the group DGROUP and the class DATA. In 
C applications, the standard data segment is created automatically. The data is always pre- 
loaded. 


10-3 DESCRIPTION 
The NONE option, if included, means that there is no data segment. To be effective, this 
option should be the only attribute of the segment. This option is available only for librar- 
ies. 

The SINGLE option, if included, means that a single segment is shared by all instances of 
the module, and is valid only for libraries. 

The MULTIPLE option means that one segment exists for each instance, and is only valid 
for applications. 

NONE, SINGLE, and MULTIPLE are mutually exclusive. 

The FIXED option, if included, means that the segment remains at a fixed memory loca- 
tion. The MOVEABLE option means that the segment can be moved if necessary, in order 
to compact memory. 

Comments There are no default attributes for data segments. The .DEF file should always explicitly 
define data-segment attributes. 

Data segments are always preloaded. 
If conflicting options are included in the same statement, LINK uses the overriding option 
to determine the segment attributes. The following list shows which options override 
which: 

MULTIPLE overrides NONE. 

SINGLE overrides NONE. 

MOVEABLE overrides FIXED. 

Example DATA MOVEABLE SINGLE 
This example tells LINK that this module has a single, moveable data segment. 

DESCRIPTION 

Syntax DESCRIPTION ‘text’ 


This statement inserts text into the application’s module. It is useful for embedding source- 
control or copyright information. 
Parameter Description 


text Specifies one or more ASCII characters. The string must be en- 
closed in single quotation marks. 
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Example DESCRIPTION ‘Microsoft Windows Template Application' 


This example embeds the text “Microsoft Windows Template Application” in the applica- 
tion module. 


EXETYPE 
Syntax EXETYPE headertype 
This statement specifies the default executable-file (EXE) header type (Windows or 
OS/2). It is required for every Windows application. 
Parameter Description 
headertype Determines the header type. When linking an application in- 
tended for the Windows environment, you must set this 
parameter to the value “WINDOWS”. For an MS OS/2 applica- 
tion, set this parameter to the value “OS/2”. 
Example EXETYPE WINDOWS 
EXPORTS 
Syntax EXPORTS exportname [ordinal-option] |]\res-option]] [[data-option]] [[parameter-option]] 


This statement defines the names and attributes of the functions to be exported to other 
applications. The EXPORTS key word marks the beginning of the definitions. It can be 
followed by any number of export definitions, each on a separate line. 


Parameter Description 


exportname Specifies one or more ASCII characters that define the function 
name. It has the following form: 


<entryname>=[internalname]] 


where the entryname parameter specifies the name to be used by 
other applications to access the exported function, and internal- 
name is an optional parameter that defines the actual name of 
the function if entryname is not the actual name. 


ordinal-option Defines the function’s ordinal value. It has the following form: 
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HEAPSIZE 
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Parameter Description 
@ordinal 


where ordinal takes an integer value that specifies the function’s 
ordinal value. The ordinal value defines the location of the func- 
tion’s name in the application’s string table. (When exporting 
functions from libraries, it is better to use an ordinal rather than 
a name; using ordinals conserves space.) 


res-option Is the optional key word RESIDENTNAME, which specifies 
that the function’s name must be resident at all times. 


data-option Is the optional key word NODATA, which specifies that the 
function is not bound to a specific data segment. When invoked, 
the function uses the current data segment. 


parameter-option Is an optional integer value that specifies the number of words 
the function expects to be passed as parameters. 


Example EXPORTS 
SampleRead=read2bin @1 8 
StringIn=stri1 @2 4 
CharTest NODATA 
This example exports the functions SampleRead, StringIn and CharTest so that other appli- 
cations, or Windows itself, can call them. 
HEAPSIZE 
Syntax HEAPSIZE bytes 


This statement defines the number of bytes needed by the application for its local heap. An 
application uses the local heap whenever it allocates local memory. 


The default heap size is zero. The minimum size is 256 bytes. For an application, the size 
of the local heap must be at least large enough to hold the current environment. 
Parameter Description 


bytes Is an integer value that specifies the heap size in bytes. It must 
not exceed 65,536 (the size of a single physical segment). 
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Example HEAPSIZE 4096 


This example sets the size of the application’s local heap to 4096 bytes. 


IMPORTS 
Syntax IMPORTS [internal-option]| modulename [entry-option] 


This statement defines the names and attributes of the functions to be imported from dy- 
namic-link libraries. The IMPORTS key word marks the beginning of the definitions. It 
can be followed by any number of import definitions, each on a separate line. 


Parameter Description 


internal-option Specifies the name that the application will use to call the func- 
tion. It has the following form: 


internal-name= 


where internal-name is one or more ASCII characters. This 
name must be unique. 


modulename Specifies one or more uppercase ASCII characters that define 
the name of the executable module that contains the function. 
The module name must match the name of the executable file. 
For example, an application with the executable file 
SAMPLE.DLL has the module name “SAMPLE”. The exe- 
cutable file must be named with the .DLL extension. 


entry-option Specifies the function to be imported. It can be one of the follow- 
ing: 
.entryname 
.entryordinal 


where entryname is the actual name of the function, and entry- 
ordinal is the ordinal value of the function. 


Example IMPORTS 
Sample.SampleRead 
write2hex=Sample.SampleWrite 
Read.1 
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LIBRARY 


LIBRARY 
Syntax 


Comments 


Example 


NAME 
Syntax 


NOTE \nstead of listing imported DLL functions in the IMPORTS statement, you can specify an “im- 
port library” for the DLL in your application’s LINK command line. It also saves space to import by ordi- 
nal. 


LIBRARY Jibraryname 


This statement defines the name of a library module. Library modules are resource mod- 
ules that contain code, data, and other resources but are not intended to be executed as an 
independent program. Like an application’s module name, a library’s module name must 
match the name of the executable file. For example, the library USER.EXE has the module 
name “USER”. 


Parameter Description 
libraryname Specifies one or more ASCII characters that define the name of 
the library module. 


The start address of the library module is determined by the library’s object files; it is an in- 
ternally defined function. 


The libraryname parameter is optional. If the parameter is not included, LINK uses the 
filename part of the executable file (that is, the name with the extension removed). 


If the .DEF file includes neither a NAME nor a LIBRARY statement, LINK assumes a 
NAME statement without a modulename parameter is desired. 
LIBRARY Utilities 


This example gives a library the module name “Utilities.” 


NAME modulename 


This statement defines the name of the application’s executable module. The module name 
identifies the module when exporting functions. 
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Parameter Description 


modulename Specifies one or more uppercase ASCII characters that define 
the name of the executable module. The module name must 
match the name of the executable file. For example, an applica- 
tion with the executable file SAMPLE.EXE has the module 
name “SAMPLE”, 


Comments The modulename parameter is optional. If the parameter is not included, LINK assumes 
that the module name matches the the filename of the executable file. For example, if you 
do not specify a module name and the executable file is named MYAPP.EXE, LINK as- 
sumes that the module name is “MYAPP”. 


If the .DEF file includes neither a NAME nor a LIBRARY statement, LINK assumes a 
NAME statement without a modulename parameter is desired. 


Example NAME Calendar 


This example gives an application the module name “Calendar”. 


SEGMENTS 


Syntax SEGMENTS segmentname [CLASS ’class-name’] [[minalloc]]\ 
[FIXEDIMOVEABLE] 
[DISCARDABLE] [SHAREDINONSHARED] [PRELOADILOADONCALL] 


This statement defines the segment attributes of additional code and data segments. 


The FIXED option, if included, means that the segment remains at a fixed memory loca- 
tion. The MOVEABLE option means that the segment can be moved if necessary, in order 
to compact memory. 


The DISCARDABLE option, if included, means that the segment can be discarded if it is 
no longer needed. 


The PRELOAD option, if included, means that the segment is loaded immediately The 
LOADONCALL option means that the segment is loaded when it is accessed or called. 
The Resource Compiler may override this option. See Tools for more information. 


Parameter Description 


segmentname Specifies a character string that names the new segment. It can 
be any name, including the standard segment names _TEXT and 
_DATA, which represent the standard code and data segments. 
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Comments 


Example 


Parameter Description 


class-name Is an optional key word that specifies the class name of the 
specified segment. If no class name is specified, LINK uses the 
class name CODE by default. 


minalloc Is an optional integer value that specifies the minimum alloca- 
tion size for the segment. 


There are no default attributes for additional segments. The .DEF file should always expli- 
citly define the attributes of additional segments. 


If conflicting options are included in the same statement, LINK uses the overriding option 
to determine the segment attributes. The following list shows which options override 
which: 


MOVEABLE overrides FIXED. 
PRELOAD overrides LOADONCALL. 


SEGMENTS 
JTEXT FIXED 
_INIT PRELOAD DISCARDABLE 
_RES CLASS 'DATA' PRELOAD DISCARDABLE 


STACKSIZE 
Syntax 


Comments 


STACKSIZE bytes 


This statement defines the number of bytes needed by the application for its local stack. An 
application uses the local stack whenever it makes function calls. 


The default stack size is zero if the application makes no function calls. If your application 
does make function calls and you specify a stack size smaller than 5K bytes, Windows au- 
tomatically sets the stack size to 5K bytes. 


Parameter Description 


bytes Is an integer value that specifies the stack size in bytes. 


Do not use the STACKSIZE statement for dynamic-link libraries. 
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Example STACKSIZE 6144 


This example sets the size of an application’s stack to 6144 bytes. 


STUB 
Syntax STUB ‘filename’ 


This statement appends the old-style executable file specified by filename to the beginning 
of the module. The executable stub should display a warning message and terminate if the 
user attempts to execute the module without having loaded Windows. The default file 
WINSTUB.EXE can be used if no other actions are required. 


Parameter Description 


filename Specifies the name of the old-style executable file that will be 
appended to the module. The name must have the DOS filename 
format. 


Comments If the file named by filename is not in the current directory, LINK searches for the file in 
the directories specified by the user’s PATH environment variable. 


Example STUB 'WINSTUB.EXE' 


This example specifies the executable file WINSTUB.EXE as the application’s stub. If a 
user tries to run this application in the DOS environment, rather than with Windows, the 
program WINSTUB.EXE starts instead. 


Chapter || Binary and Ternary 
17 Raster-Operation Codes 


This chapter lists and describes the binary and ternary raster operations used by 
the graphics device interface (GDI). A binary raster operation uses two operands: 
a pen and a destination bitmap. A ternary raster operation uses three operands: a 
source bitmap, a brush, and a destination bitmap. Both binary and ternary raster 
operations use Boolean operators. 


11.1 Binary Raster Operations 


This section lists the binary raster-operation codes used by the GetROP2 and 
SetROP2 functions. Raster-operation codes define how GDI combines the bits 
from the selected pen with the bits in the destination bitmap. 


Each raster-operation code represents a Boolean operation in which the selected 
pen and the destination bitmap are combined. There are two operands used in 


these operations: 
D Destination bitmap 
P Selected pen 


The Boolean operators used in these operations are as follows: 


a Bitwise AND 

n Bitwise NOT (inverse) 

fo) Bitwise OR 

X Bitwise Exclusive OR (XOR) 


All Boolean operations are presented in reverse Polish notation. For example, the 
following operation replaces the destination with a combination of the pen and 
the selected brush: 


DPo 
Each raster-operation code is a 32-bit integer value whose high-order word is a 


Boolean operation index and whose low-order word is the operation code. The 
16-bit operation index is a zero-extended 8-bit value that represents the result of 
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the Boolean operation on predefined pen and destination values. For example, 
the operation indexes for the DPo and DPan operations are shown in Table 11.1: 


Table 11.1 Operation Indexes for DPo and DPan 


P D PSo DPSoo 
0 0 0 1 
0 1 1 1 
1 0 1 1 
1 1 1 0 


The following list outlines the drawing modes and the Boolean operations that 
they represent: 


Raster Operation Boolean Operation 
R2_BLACK 0 
R2_COPYPEN P 
R2_MASKNOTPEN DPna 
R2_MASKPEN DPa 
R2_MASKPENNOT PDna 
R2_MERGENOTPEN DPno 
R2_MERGEPEN DPo 
R2_MERGEPENNOT PDno 
R2_NOP D 
R2_NOT Dn 
R2_NOTCOPYPEN Pn 
R2_NOTMASKPEN DPan 
R2_NOTMERGEPEN DPon 
R2_NOTXORPEN DPxn 
R2_WHITE 1 
R2_XORPEN DPx 


When a monochrome device is used, GDI maps the value zero to black and the 
value 1 to white. Given an application that attempts to draw with a black pen on 
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a white destination by using the available binary raster operations, the following 


results will occur: 


Raster Operation 
R2_BLACK 
R2_COPYPEN 
R2_MASKNOTPEN 
R2_MASKPEN 
R2_MASKPENNOT 
R2_MERGENOTPEN 
R2_MERGEPEN 
R2_MERGEPENNOT 
R2_NOP 

R2_NOT 
R2_NOTCOPYPEN 
R2_NOTMASKPEN 
R2_NOTMERGEPEN 
R2_NOTXORPEN 
R2_WHITE 
R2_XORPEN 


Visible black line 
Visible black line 
No visible line 
Visible black line 
Visible black line 
No visible line 
Visible black line 
Visible black line 
No visible line 
Visible black line 
No visible line 
No visible line 
Visible black line 
Visible black line 
No visible line 


No visible line 


When a color device is used, GDI uses RGB values to represent the colors of the 
pen and the destination. An RGB color value is a long integer that contains a red, 
a green, and a blue color field, each specifying the intensity of the given color. In- 
tensities range from 0 to 255. The values are packed in the three low-order bytes 
of the long integer. The color of a pen is always a solid color, but the color of the 
destination may be a mixture of any two or three colors. Given an application 
that attempts to draw with a white pen on a blue destination by using the availa- 
ble binary raster operations, the following results will occur: 


Raster Operation Result 
R2_BLACK Visible black line 
R2_COPYPEN Visible white line 


R2_MASKNOTPEN Visible black line 
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Raster Operation 
R2_MASKPEN 
R2_MASKPENNOT 
R2_MERGENOTPEN 
R2_MERGEPEN 
R2_MERGEPENNOT 
R2_NOP 

R2_NOT 
R2_NOTCOPYPEN 
R2_NOTMASKPEN 
R2_NOTMERGEPEN 
R2_NOTXORPEN 
R2_WHITE 
R2_XORPEN 


Invisible blue line 
Visible red/green line 
Invisible blue line 
Visible white line 
Visible white line 
Invisible blue line 
Visible red/green line 
Visible black line 
Visible red/green line 
Visible black line 
Invisible blue line 
Visible white line 


Visible red/green line 


11.2 Ternary Raster Operations 


This section lists the ternary raster-operation codes used by the BitBlt, PatBlt, 
and StretchBlt functions. Ternary raster-operation codes define how GDI com- 
bines the bits in a source bitmap with the bits in the destination bitmap. 


Each raster-operation code represents a Boolean operation in which the source, 
the selected brush, and the destination bitmap are combined. There are three oper- 
ands used in these operations: 


Destination bitmap 
P Selected brush (also called pattern) 


Source bitmap 


The Boolean operators used in these operations are as follows: 


a Bitwise AND 
n Bitwise NOT (inverse) 
oO Bitwise OR 


x Bitwise Exclusive OR (XOR) 
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All Boolean operations are presented in reverse Polish notation. For example, the 
following operation replaces the destination with a combination of the source and 
brush: 


PSo 


The following operation combines the source and brush with the destination 
(there are alternate spellings of the same function, so although a particular spel- 
ling may not be in the list, an equivalent form will be): 


DPSoo 


Each raster-operation code is a 32-bit integer value whose high-order word is a 
Boolean operation index and whose low-order word is the operation code. The 
16-bit operation index is a zero-extended, 8-bit value that represents the result of 
the Boolean operation on predefined brush, source, and destination values. For 
example, the operation indexes for the PSo and DPSoo operations are shown in 
Table 11.2: 


Table 11.2 Operation Indexes for PSo and DPSoo 


P S D PSo DPSoo 
0 0 0 0 0 

0 0 1 0 1 

0 1 0 1 1 

0 1 1 1 1 

1 0 0 1 1 

1 0 1 1 1 

1 1 0 1 1 

1 1 1 1 1 
Operation index: OOFC OOFE 


In this case, PSo has the operation index OOFC (read from the bottom up); DPSoo 
has the operation index OOFE. These values define the location of the correspond- 
ing raster-operation codes, as shown in Table 11.1, “Operation Indexes for DPo 
and DPan.” The PSo operation is in line 252 (FCh) of the table; DPSoo is in line 
254 (FEh). 


The most commonly used raster operations have been given special names in the 
Windows include file, WINDOWS.H. You should use these names whenever 
possible in your applications. 


When the source and destination are monochrome, a bit value of zero represents 
a black pixel and a bit value of 1 represents a white pixel. When the source and 
the destination are color, those colors are represented with RGB values. For more 
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information about RGB values, see the RGB structure in Chapter 7, “Data Types 


and Structures.” 


Table 11.3 lists the raster-operation codes: 


Table 11.3 Raster-Operation Codes 


Boolean Hex Boolean Common 
Function ROP Function Name 
in Hex in Reverse Polish 

00 00000042 0 BLACKNESS 
01 00010289 DPSoon - 

02 00020C89 DPSona - 

03 000300AA PSon - 

04 00040C88 SDPona - 

05 000500A9 DPon - 

06 00060865 PDSxnon - 

07 000702C5 PDSaon - 

08 O0080F08 SDPnaa - 

09 00090245 PDSxon - 

0A 000A0329 DPna - 

OB O000BOB2A PSDnaon - 

0c 000C0324 SPna - 

0D O00D0B25 PDSnaon - 

OE OOOEO8A5 PDSonon - 

OF OOOFO001 Pn - 

10 00100C85 PDSona - 

11 001100A6 DSon NOTSRCERASE 
12 00120868 SDPxnon - 

13 001302C8 SDPaon - 

14 00140869 DPSxnon - 

15 001502C9 DPSaon - 

16 00165CCA PSDPSanaxx - 

17 00171D54 SSPxDSxaxn - 

18 00180D59 SPxPDxa - 

19 00191CC8 SDPSanaxn - 

1A 001A06C5 PDSPaox - 

1B 001B0768 SDPSxaxn - 


1C 001CO6CA PSDPaox - 
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Table 11.3 Raster-Operation Codes (continued) 


Boolean Hex Boolean Common 
Function ROP Function Name 
in Hex in Reverse Polish 

1D 001D0766 DSPDxaxn - 
1E OO1EO1A5 PDSox - 
1F 001F0385 PDSoan - 
20 00200F09 DPSnaa - 
21 00210248 SDPxon - 
22 00220326 DSna - 
23 00230B24 SPDnaon - 
24 00240D55 SPxDSxa - 
25 00251CCS5 PDSPanaxn - 
26 002606C8 SDPSaox - 
27 00271868 SDPSxnox - 
28 00280369 DPSxa - 
29 002916CA PSDPSaoxxn - 
2A 002A0CC9 DPSana - 
2B 002B1D58 SSPxPDxaxn - 
2C 002C0784 SPDSoax . 
2D 002D060A PSDnox - 
2E 002E064A PSDPxox - 
2F 002FOE2A PSDnoan - 
30 0030032A PSna - 
31 00310B28 SDPnaon - 
32 00320688 SDPSoox - 
33 00330008 Sn NOTSRCCOPY 
34 003406C4 SPDSaox - 
35 00351864 SPDSxnox - 
36 003601A8 SDPox - 
37 00370388 SDPoan - 
38 0038078A PSDPoax - 
39 00390604 SPDnox - 
3A 003A0644 SPDSxox - 
3B 003B0E24 SPDnoan - 
3C 003C004A PSx - 


3D 003D18A4 SPDSonox - 
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Table 11.3 Raster-Operation Codes (continued) 


Boolean Hex Boolean Common 
Function ROP Function Name 

in Hex in Reverse Polish 

3E 003E1B24 SPDSnaox - 

3F 003FOOEA PSan - 

40 00400F0A PSDnaa - 

41 00410249 DPSxon - 

42 00420D5D SDxPDxa - 

43 00431CC4 SPDSanaxn - 

44 00440328 SDna SRCERASE 
45 00450B29 DPSnaon - 

46 004606C6 DSPDaox - 

47 0047076A PSDPxaxn - 

48 00480368 SDPxa - 

49 004916C5 PDSPDaoxxn - 

4A 00440789 DPSDoax - 

4B 004B0605 PDSnox - 

4C 004COCC8 SDPana - 

4D 004D1954 SSPxDSxoxn - 

4E 004E0645 PDSPxox - 

4F 004FOE25 PDSnoan - 

50 00500325 PDna - 

51 00510B26 DSPnaon - 

52, 005206C9 DPSDaox - 

53 00530764 SPDSxaxn - 

54 005408A9 DPSonon - 

55 00550009 Dn DSTINVERT 
56 005601 A9 DPSox - 

37 00570389 DPSoan - 

58 00580785 PDSPoax - 

59 00590609 DPSnox - 

5A 005A0049 DPx PATINVERT 
5B 005B18A9 DPSDonox - 

5C 005C0649 DPSDxox - 

5D 005D0E29 DPSnoan - 


5E 005E1B29 DPSDnaox - 
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Table 11.3. Raster-Operation Codes (continued) 


Boolean Hex Boolean Common 
Function ROP Function Name 
in Hex in Reverse Polish 

5F OOSFOOE9 DPan - 
60 00600365 PDSxa - 
61 006116C6 DSPDSaoxxn - 
62 00620786 DSPDoax - 
63 00630608 SDPnox - 
64 00640788 SDPSoax - 
65 00650606 DSPnox - 
66 00660046 DSx SRCINVERT 
67 006718A8 SDPSonox - 
68 006858A6 DSPDSonoxxn - 
69 00690145 PDSxxn - 
6A 006A01E9 DPSax - 
6B 006B178A PSDPSoaxxn - 
6C 006C01E8 SDPax - 
6D 006D1785 PDSPDoaxxn - 
6E 006E1E28 SDPSnoax - 
6F 006FOC65 PDSxnan - 
70 00700CCS5 PDSana - 
71 00711D5C SSDxPDxaxn - 
72 00720648 SDPSxox - 
73 00730E28 SDPnoan - 
74 00740646 DSPDxox - 
wD 00750E26 DSPnoan - 
76 00761B28 SDPSnaox - 
77 007700E6 DSan - 
78 007801E5 PDSax - 
79 00791786 DSPDSoaxxn - 
7A 007A1E29 DPSDnoax - 
7B 007B0C68 SDPxnan - 
1G 007C1E24 SPDSnoax - 
7D 007D0C69 DPSxnan - 
TE 007E0955 SPxDSxo - 


TF 007F03C9 DPSaan . 
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Table 11.3 Raster-Operation Codes (continued) 


Boolean Hex Boolean Common 
Function ROP Function Name 
in Hex in Reverse Polish 

80 008003E9 DPSaa - 
81 00810975 SPxDSxon - 
82 00820C49 DPSxna - 
83 0083 1E04 SPDSnoaxn - 
84 00840C48 SDPxna - 
85 00851E05 PDSPnoaxn - 
86 008617A6 DSPDSoaxx - 
87 008701C5 PDSaxn - 
88 008800C6 DSa SRCAND 
89 00891B08 SDPSnaoxn - 
8A 008A0E06 DSPnoa - 
8B 008B0666 DSPDxoxn - 
8C 008COE08 SDPnoa - 
8D 008D0668 SDPSxoxn - 
8E 008E1D7C SSDxPDxax - 
8F OO8FOCES PDSanan - 
90 00900C45 PDSxna - 
91 00911E08 SDPSnoaxn - 
92 009217A9 DPSDPoaxx - 
93 009301C4 SPDaxn - 
94 009417AA PSDPSoaxx - 
95 009501C9 DPSaxn - 
96 00960169 DPSxx - 
97 0097588A PSDPSonoxx - 
98 00981888 SDPSonoxn - 
99 00990066 DSxn - 
9A 009A0709 DPSnax - 
9B 009B07A8 SDPSoaxn - 
9C 009C0704 SPDnax - 
9D 009D07A6 DSPDoaxn - 
9E 009E16E6 DSPDSaoxx - 
9F 009F0345 PDSxan - 


AO 00A000C9 DPa - 
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Table 11.3 Raster-Operation Codes (continued) 


Boolean Hex Boolean Common 
Function ROP Function Name 
in Hex in Reverse Polish 

Al 00A11B05 PDSPnaoxn - 

A2 00A20E09 DPSnoa - 

A3 00A30669 DPSDxoxn - 

A4 00A41885 PDSPonoxn - 

AS 00A50065 PDxn - 

A6 00A60706 DSPnax - 

AT 00A707A5 PDSPoaxn - 

A8 O0A803A9 DPSoa - 

A9 00A90189 DPSoxn - 

AA 00AA0029 D - 

AB OOAB0889 DPSono - 

AC 00AC0744 SPDSxax - 

AD OOADO6E9 DPSDaoxn - 

AE OOAEOB06 DSPnao - 

AF OOAF0229 DPno - 

BO OOBOOE0S PDSnoa - 

Bl 00B10665 PDSPxoxn - 

B2 00B21974 SSPxDSxox - 

B3 00B30CE8 SDPanan - 

B4 00B4070A PSDnax - 

B5 00B507A9 DPSDoaxn - 

Bo 00B616E9 DPSDPaoxx - 

B7 00B70348 SDPxan - 

B8 00B8074A PSDPxax - 

B9 O00B906E6 DSPDaoxn - 

BA OOBAOB09 DPSnao - 

BB 00BB0226 DSno MERGEPAINT 
BC OOBC1CE4 SPDSanax - 

BD OOBDOD7D SDxPDxan - 

BE 00BE0269 DPSxo - 

BF OOBFO8C9 DPSano - 

CO O00CO00CA PSa MERGECOPY 


Cl 00C11B04 SPDSnaoxn - 
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Table 11.3 Raster-Operation Codes (continued) 


Boolean Hex Boolean Common 
Function ROP Function Name 
in Hex in Reverse Polish 

C2 00C21884 SPDSonoxn - 
C3 00C3006A PSxn - 
C4 00C40E04 SPDnoa - 
GS 00C50664 SPDSxoxn - 
C6 00C60708 SDPnax - 
C7 O00C707AA PSDPoaxn - 
C8 00C803A8 SDPoa - 
C9 00C90184 SPDoxn - 
CA 00CA0749 DPSDxax - 
CB OOCBO6E4 SPDSaoxn - 
CC 00CC0020 S SRCCOPY 
CD OO0CDO888 SDPono - 
CE OOCEOB08 SDPnao - 
CF 00CF0224 SPno - 
DO OODOOEOA PSDnoa - 
D1 00D1066A PSDPxoxn - 
D2 00D20705 PDSnax - 
D3 00D307A4 SPDSoaxn - 
D4 00D41D78 SSPxPDxax - 
D5 OODSOCE9 DPSanan - 
D6 00D616EA PSDPSaoxx - 
D7 00D70349 DPSxan - 
D8 00D80745 PDSPxax - 
D9 OOD906E8 SDPSaoxn - 
DA OODAICE9 DPSDanax - 
DB OODBOD75 SPxDSxan - 
DC OODCOB04 SPDnao - 
DD 00DD0228 SDno = 
DE OODE0268 SDPxo - 
DF OODFO8C8 SDPano - 
EO 00E003A5 PDSoa - 
El 00E10185 PDSoxn a 


E2 00E20746 DSPDxax - 
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Table 11.3 Raster-Operation Codes (continued) 


Boolean Hex Boolean Common 
Function ROP Function Name 

in Hex in Reverse Polish 

E3 O0E306EA PSDPaoxn - 

E4 00E40748 SDPSxax - 

ES OOES06E5 PDSPaoxn - 

E6 00E61CE8 SDPSanax - 

E7 00E70D79 SPxPDxan - 

E8 00E81D74 SSPxDSxax - 

E9 OOE9SCE6 DSPDSanaxxn - 

EA OOEA02E9 DPSao - 

EB OOEB0849 DPSxno - 

EC OOECO2E8 SDPao - 

ED OOED0848 SDPxno - 

EE OOEE0086 DSo SRCPAINT 
EF OOEFOA08 SDPnoo - 

FO 00F00021 P PATCOPY 
Fl O0F10885 PDSono - 

F2 OOF20B05 PDSnao - 

F3 00F3022A PSno - 

F4 OOF40B0A PSDnao - 

F5 00F50225 PDno - 

F6 00F60265 PDSxo - 

F7 OOF708CS5 PDSano - 

F8 OOF802E5 PDSao - 

F9 O00F90845 PDSxno - 

FA OOFA0089 DPo - 

FB OOFBOA09 DPSnoo PATPAINT 
FC OOFCO08A PSo - 

FD OOFDOA0A PSDnoo - 

FE OOFE02A9 DPSoo - 

FF OOFF0062 1 WHITENESS 
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17.3 Summary 


Raster-operation codes define how GDI combines the bits of a source bitmap 
with the bits of a destination bitmap. For more information on topics related to 
raster-operation codes, see the following: 


Topic Reference 

Using raster-operation Reference, Volume 1: Chapter 2, “Graphics 

codes with GDI functions Device Interface Functions,” and Chapter 4, 
“Functions Directory” 

Setting the current drawing Reference, Volume I: Chapter 4, “Functions 

mode with SetROP2 Directory” 


Guide to Programming: Chapter 6, “The 
Cursor, the Mouse, and the Keyboard” 


Bitmaps and raster Guide to Programming: Chapter 11, 
operations “Bitmaps” 


Chapter 


12 


Printer Escapes 


This chapter contains an alphabetical list of the individual Microsoft Windows 
printer escapes. The printer escapes allow applications to access facilities of a 
particular output device that are not available directly through the graphics 
device interface (GDI). The escape calls are made by an application, translated 
by Windows, and then sent to the printer device driver. 
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ABORTDOC 
Syntax short Escape(hDC, ABORTDOC, NULL, NULL, NULL) 


This escape terminates the current job, erasing everything the application has written to the 
device since the last ENDDOC escape. 


The ABORTDOC escape should be used to terminate: 
= Printing operations that do not specify an abort function using the SETABORTPROC 
escape 


= Printing operations that have not yet reached their first NEWFRAME or NEXT- 
BAND escape call 


Parameter Type/Description 


hDC HDC Identifies the device context. 


Return Value The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is negative. 


Comments If an application encounters a printing error or a canceled print operation, it must not at- 
tempt to terminate the operation by using the Escape function with either the ENDDOC 
or ABORTDOC escape. GDI automatically terminates the operation before returning the 
error value. 


If the application displays a dialog box to allow the user to cancel the print operation, it 
must send the ABORTDOC escape before destroying the dialog box. 


The application must send the ABORTDOC escape before freeing the procedure-instance 
address of the abort function, if any. 


BANDINFO 
Syntax short Escape(iDC, BANDINFO, sizeof(BANDINFOSTRUCT), /pinData, IpOutData) 


This escape copies information about a device with banding capabilities to a structure 
pointed to by the pOutData parameter. It is implemented only for devices that use band- 
ing. 


Banding is a property of an output device that allows a page of output to be stored in a 
metafile and divided into bands, each of which is sent to the device to create a complete 


page. 
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BANDINFO 


Return Value 


Comments 


The information copied to the structure pointed to by /pOutData includes: 


= A value that indicates whether there are graphics in the next band 
= A value that indicates whether there is text on the page 


= ARECT data structure that contains a bounding rectangle for all graphics on the page 


The /pOutData parameter is NULL if no data are returned. 


The /pInData parameter specifies information sent by the application to the device driver. 
This information is read by the device driver only on the first BANDINFO escape call on 
a page. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpInData BANDINFOSTRUCT FAR * Points to a BANDINFOSTRUCT 


data structure that contains information to be passed to the driver. See 
the following “Comments” section for more information on the BAND- 
INFOSTRUCT data structure. 


IpOutData BANDINFOSTRUCT FAR * Points to a BANDINFOSTRUCT 
data structure that contains information returned by the driver. See the 
following “Comments” section for more information on the BAND- 
INFOSTRUCT data structure. 


The return value specifies the outcome of the escape. It is 1 if the escape is successful. It is 
zero if the function fails or is not implemented by the driver. 


The BANDINFOSTRUCT data structure contains information about the contents of a 


page and supplies a bounding rectangle for graphics on the page. The following shows the 
format of BANDINFOSTRUCT: 


typedef struct { 
BOOL fGraphicsFlag; 
BOOL fTextFlag; 
RECT GraphicsRect; 
} BANDINFOSTRUCT ; 


The BANDINFOSTRUCT structure has the following fields: 
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Field Description 


fGraphicsFlag Is TRUE if graphics are or are expected to be on the page or in 
the band; otherwise, it is FALSE. 


fTextFlag Is TRUE if text is or is expected to be on the page or in the 
band; otherwise, it is FALSE. 


GraphicsRect Contains a RECT data structure that supplies a bounding region 
for all graphics on the page. 


Table 12.1 shows the meaning of these fields, depending on which parameter contains the 
structure. 


Table 12.1 Meaning of BANDINFOSTRUCT Fields 


Field When Used in /pInData When Used in /pOutData 

fGraphicsFlag TRUE if the application is inform- TRUE if the driver is informing the 
ing the driver that graphics are on application that it expects graphics 
the page. in this band. 

fTextFlag TRUE if the application is inform- TRUE if the driver is informing the 
ing the driver that text ison the page. application that it expects text in 

this band. 

GraphicsRect Supplies the bounding rectangle for No valid return data. 

all graphics on the page. 


An application should call this escape immediately after each call to the NEXTBAND 
escape. It is in reference to the band the driver returned to that escape. 


An application should use this escape in the following manner: 


On the first band, the driver may give the application a full-page band and ask for text only 
(fGraphicsFlag is set to FALSE and fTextFlag is set to TRUE). The application sends 
only text to the driver. 


If in the first band the application indicated that it had graphics (fGraphicsFlag is set to 
TRUE), or that the driver encountered vector fonts, then the driver will band the rest of the 
page. If there are no graphics or vector fonts, then the next NEXTBAND will return an 
empty rectangle to indicate that the application should move on to the next page. 


If there are graphics but no vector fonts (the application set fGraphicsFlag to TRUE, but 
there were no graphics in the first full-page text band), then for subsequent bands the 
driver may optionally band only into the rectangle the application passed. This rectangle 
bounds all graphics on the page. If there are vector fonts, then the driver will band the en- 
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BEGIN_PATH 


BEGIN_PATH 
Syntax 


Return Value 


Comments 


tire width and depth of the page with fTextFlag set to TRUE. It will also set fGraphics- 
Flag to true if the application set it. 


The driver assumes that an application using BANDINFO will only send text in the first 
full-page text band since that is all the driver requested. Therefore, if the driver encounters 
a vector font or graphics in the band, it assumes they were generated by a text primitive 
and sets fTextFlag to TRUE for all subsequent graphics bands so they can be output as 
graphics. If the application does not satisfy this expectation, the image will still be 
generated properly, but the driver will spend time sending spurious text primitives to 
graphics bands. 


Older drivers written before the BANDINFO escape was designed used full-page banding 
for text. If a particular driver does not support the BANDINFO escape but sets 
RC_BANDING, the application can detect full-page banding for text by determining if the 
first band on the page covers the entire page. 


short Escape(hDC, BEGIN _PATH, NULL, NULL, NULL) 


This escape opens a path. A path is a connected sequence of primitives drawn in succes- 
sion to form a single polyline or polygon. Paths enable applications to draw complex 
borders, filled shapes, and clipping areas by supplying a collection of other primitives that 
define the desired shape. 


Printer escapes supporting paths enable applications to render images on sophisticated dev- 
ices such as PostScript® printers without generating huge polygons to simulate the images. 


To draw a path, an application first issues the BEGIN_PATH escape. It then draws the 
primitives defining the border of the desired shape and issues an END_PATH escape. The 
END_PATH escape includes a parameter specifying how the path is to be rendered. 


Parameter Type/Description 


hDC HDC Identifies the device context. 


The return value specifies the current path nesting level. If the escape is successful, the re- 
turn value is the number of BEGIN_PATH escape calls without a corresponding 
END_PATH escape call. Otherwise, the return value is zero. 


An application may begin a subpath within another path. If the subpath is closed, it is 
treated exactly like a polygon. If it is open, it is treated exactly like a polyline. 


An application may use the CLIP_TO_PATH escape to define a clipping area correspond- 
ing to the interior or exterior of the currently open path. 
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CLIP_TO_PATH 
Syntax 


Return Value 


Comments 


short Escape(hDC, CLIP_TO_PATH, sizeof(int), /pClipMode, NULL) 


This escape defines a clipping area bounded by the currently open path. It enables the 
application to save and restore the current clipping area and to set up an inclusive or exclu- 
sive clipping area bounded by the currently open path. If the path defines an inclusive clip- 
ping area, portions of primitives falling outside the interior bounded by the path are 
clipped. If the path defines an exclusive clipping area, portions of primitives falling inside 
the interior are clipped. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpClipMode LPINT Points to a short integer specifying the clip- 
ping mode. It can be one of the following values: 
Value Meaning 
CLIP_SAVE (0) Saves the current clip- 
ping area. 
CLIP_RESTORE (1) Restores the previous 
clipping area. 
CLIP_INCLUSIVE (2) Sets an inclusive clipping 
area. 
CLIP_EXCLUSIVE (3) Sets an exclusive clip- 
ping area. 


The return value specifies the outcome of the escape. It is nonzero if the escape was 
successful. Otherwise, it is zero. 


To clip a set of primitives against a path, an application should follow these steps: 


1. Save the current clipping area using the CLIP_TO_PATH escape. 
2. Begin a path using the BEGIN_PATH escape. 


3. Draw the primitives bounding the clipping area. 
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DEVICEDATA 


DEVICEDATA 
Syntax 


DRAFTMODE 
Syntax 


Return Value 


Comments 


4. Set the clipping area using the CLIP_TO_PATH escape. 
5. Close the path using the END_PATH escape. 
6. Draw the primitives to be clipped. 


7. Restore the original clipping area using the CLIP_TO_PATH escape. 


short Escape(hDC, DEVICEDATA, nCount, lpInData, IpOutData) 


This escape is identical to the PASSTHROUGH escape. See the description of PASS- 
THROUGH for further information. 


short Escape(hDC, DRAFTMODE, sizeof(int), /pDraftMode, NULL) 


This escape turns draft mode off or on. Turning draft mode on instructs the device driver to 
print faster and with lower quality (if necessary). The draft mode can be changed only at 
page boundaries, for example, after a NEWFRAME escape directing the driver to ad- 
vance to a new page. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
[pDraftMode LPINT Points to a short-integer value that specifies the draft 
mode. It may be one of the following values: 
Value Meaning 
0 Specifies draft mode off. 
i} Specifies draft mode on. 


The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is negative. 


The default draft mode is off. 


DRAWPATTERNRECT 
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DRAWPATTERNRECT 


Syntax 


Return Value 


Comments 


short Escape(hDC, DRAWPATTERNRECT, sizeof(PRECTSTRUCT), /pinData, 
NULL) 


This escape creates a pattern, gray scale, or solid black rectangle by using the pattern/rule 
capabilities of Page Control Language (PCL) on Hewlett-Packard®@ LaserJet® or LaserJet- 


compatible printers. A gray scale is a gray pattern that contains a specific mixture of black 
and white pixels. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
[pInData PRECT_STRUCT FAR * Points toa PRECT_STRUCT 


data structure that describes the rectangle. See the following 
“Comments” section for more information on the 
PRECT_STRUCT data structure. 


The return value specifies the outcome of the escape. It is 1 if the escape is successful. 
Otherwise, it is zero. 


The /pInData parameter points to a PRECT_STRUCT data structure that defines the 
rectangle to be created. The PRECT_STRUCT structure has the following format: 


typedef struct { 
POINT prPosition; 
POINT prSize; 
WORD prStyle; 
WORD = prPattern; 
} PRECT_STRUCT; 


This structure has the following fields: 


Field Description 

prPosition Specifies the upper-left corner of the rectangle. 

prSize Specifies the lower-right corner of the rectangle. 

prStyle Specifies the type of pattern. It may be one of the following 


values: 
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Field Description 

Value Meaning 

0 Black rule. 

1 White rule that erases bitmap data previously 
written to same area; this pattern is available on 
the HP LaserJet IIP only. 

2 Gray scale. 

3 HP-defined. 

prPattern Specifies the pattern. It is ignored for a black rule. It speci- 

fies the percentage of gray for a gray-scale pattern. It 

represents one of six Hewlett-Packard-defined patterns. 

An application should use the QUERYESCSUPPORT escape to determine whether a 
device is capable of drawing patterns and rules before using the DRAWPATTERNRECT 
escape. If an application uses the BANDINFO escape, all patterns and rectangles sent by 
using DRAWPATTERNRECT should be treated as text and sent on a text band. 
Do not try to erase patterns and rules created with the DRAWPATTERNRECT escape by 
placing opaque objects over them. To erase such patterns and rules, use the function calls 
provided by GDI. 

ENABLEDUPLEX 

Syntax short Escape(hDC, ENABLEDUPLEX, sizeof(WORD), /pInData, NULL) 


This escape enables the duplex printing capabilities of a printer. A device that possesses du- 
plex printing capabilities is able to print on both sides of the output medium. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpInData WORD FAR * Points to an unsigned 16-bit integer that 


specifies whether duplex or simplex printing is used. It may 
be one of the following values: 
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Return Value 


Comments 


Parameter Type/Description 
Value Meaning 
0 Simplex 
1 Duplex with vertical binding 
2 Duplex with horizontal binding 


The return value specifies the outcome of the escape. It is 1 if the escape is successful. 
Otherwise, it is zero. 


An application should use the QUERYESCSUPPORT escape to determine whether an 
output device is capable of creating duplex output. If QUERYESCSUPPORT returns a 
nonzero value, the application should send the ENABLEDUPLEX escape even if simplex 
printing is desired. This guarantees replacement of any values set in the driver-specific 
dialog box. If duplex printing is enabled and an uneven number of NEXTFRAME 
escapes are sent to the driver prior to the ENDDOC escape, the driver will eject an addi- 
tional page before ending the print job. 


ENABLEPAIRKERNING 


Syntax 


short Escape(hDC, ENABLEPAIRKERNING, sizeof(int), /pNewKernF lag, 
IpOldKernFlag) 


This escape enables or disables the driver’s ability to kern character pairs automatically. 
Kerning is the process of adding or subtracting space between characters in a string of text. 


When pair kerning is enabled, the driver automatically kerns those pairs of characters that 
are listed in the font’s character-pair kerning table. The driver reflects this kerning both on 
the printer and in GetTextExtent function calls. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
lpNewKernFlag LPINT Points to a short-integer value that specifies whether 


automatic pair kerning is to be enabled (1) or disabled (0). 


IpOldKernFlag LPINT Points to a short-integer value that will receive the 
previous automatic pair-kerning value. 
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ENABLERELATIVEWIDTHS 


Return Value 


Comments 


The return value specifies the outcome of the escape. It is 1 if the escape is successful; it is 
zero if the escape is not successful or not implemented. 


The default state of this escape is zero; automatic character-pair kerning is disabled. 


A driver does not have to support the ENABLEPAIRKERNING escape just because it 
supplies the character-pair kerning table to the application via the GETPAIRKERN- 
TABLE escape. In the case where the GETPAIRKERNTABLE escape is supported but 
the ENABLEPAIRKERNING escape is not, the application must properly space the 
kerned characters on the output device using the ExtTextOut function. 


ENABLERELATIVEWIDTHS 


Syntax 


Return Value 


Comments 


short Escape(4DC, ENABLERELATIVEWIDTHS, sizeof(int), /pNewWidthFlag, 
[pOldWidthF lag) 


This escape enables or disables relative character widths. When relative widths are dis- 
abled (the default), each character’s width can be expressed as a number of device units. 
This guarantees that the extent of a string will equal the sum of the extents of the 
characters in the string. This allows applications to build an extent table by using one- 
character GetTextExtent function calls. 


When relative widths are enabled, the sum of a string may not equal the sum of the widths 
of the characters. Applications that enable this feature are expected to retrieve the font’s ex- 
tent table and compute relatively scaled string widths. 


Parameter Type/Description 
hDC HDC Identifies the device context. 


IpNewWidthF lag LPINT Points to a short-integer value that specifies whether 
relative widths are to be enabled (1) or disabled (0). 


[pOldWidthF lag LPINT Points to a short-integer value that will receive the 
previous relative character width value. 


The return value specifies the outcome of the escape. It is 1 if the escape is successful; it is 
zero if the escape is not successful or not implemented. 


The default state of this escape is zero; relative character widths are disabled. 


The values specified as font units and accepted and returned by the escapes described in 
this chapter are returned in the relative units of the font when the ENABLERELATIVE- 
WIDTHS escape is enabled. 
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It is assumed that only linear-scaling devices will be dealt with in a relative mode. Non- 
linear-scaling devices do not implement this escape. 


ENDDOC 
Syntax short Escape(hDC, ENDDOC, NULL, NULL, NULL) 


This escape ends a print job started by a STARTDOC escape. 


Parameter Type/Description 


hDC HDC Identifies the device context. 


Return Value The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is negative. 


Comments If an application encounters a printing error or a canceled print operation, it must not at- 
tempt to terminate the operation by using the Escape function with either the ENDDOC 
or ABORTDOC escape. GDI automatically terminates the operation before returning the 
error value. 


If the application displays a dialog box to allow the user to cancel the print operation, it 
must send the ENDDOC escape before destroying the dialog box. 


The application must send the ENDDOC escape before freeing the procedure-instance 
address of the abort function, if any. 


END_PATH 
Syntax short Escape(4DC, END_PATH, sizeof(PATH_INFO), /pInData, NULL) 


This escape ends a path. A path is a connected sequence of primitives drawn in succession 
to form a single polyline or polygon. Paths enable applications to draw complex borders, 
filled shapes, and clipping areas by supplying a collection of other primitives defining the 
desired shape. 


Printer escapes supporting paths enable applications to render images on sophisticated dev- 
ices such as PostScript printers without generating huge polygons to simulate them. 
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END_PATH 


Return Value 


Comments 


To draw a path, an application first issues the BEGIN_PATH escape. It then draws the 
primitives defining the border of the desired shape and issues an END_PATH escape. 


The END_PATH escape takes as a parameter a pointer to a structure specifying the man- 
ner in which the path is to be rendered. The structure specifies whether or not the path is to 
be drawn and whether it is open or closed. Open paths define polylines, and closed paths 
define fillable polygons. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpInData PATH_INFO FAR * Points to a PATH_INFO data structure 


that defines how the path is to be rendered. See the following 
“Comments” section for more information on this data structure. 


The return value specifies the current path nesting level. If the escape is successful, the re- 
turn value is the number of BEGIN_PATH escape calls without a corresponding 
END_PATH call. Otherwise, the return value is —1. 


An application may begin a subpath within another path. If the subpath is closed, it is 
treated exactly like a polygon. If it is open, it is treated exactly like a polyline. 


An application may use the CLIP_TO_PATH escape to define a clipping area correspond- 
ing to the interior or exterior of the currently open path. 


The /pinData parameter points to a PATH_INFO data structure that specifies how to ren- 
der the path. This data structure has the following form: 


typedef struct { 


short RenderMode; 
BYTE FillMode; 
BYTE BkMode; 
LOGPEN Pen; 


LOGBRUSH Brush; 
DWORD BkColor; 
} PATH_INFO; 


END_PATH 
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The PATH_INFO structure has the following fields: 


Field 
RenderMode 


FillMode 


BkMode 


Pen 
Brush 


BkColor 


Description 


Specifies how the path is to be rendered. It may be one of the fol- 


lowing values: 


Value. 
NO_DISPLAY (0) 
OPEN (1) 
CLOSED (2) 


Meaning 
The path is not drawn. 
The path is drawn as an open polygon. 


The path is drawn as a closed polygon. 


Specifies how the path is to be filled. It can be one of the follow- 


ing values: 


Value 


ALTERNATE (1) 


WINDING (2) 


Meaning 


The fill is done using the alternate fill 
algorithm. 


The fill is done using the winding fill 
algorithm. 


Specifies the background mode for filling the path. It can be one 


of the following values: 


Value 


OPAQUE 


TRANSPARENT 


Meaning 


The background is filled with the 
background color before the brush is 
drawn. 


The background is not changed. 


Specifies the pen with which the path is to be drawn. If Render- 
Mode is set to NO_DISPLAY, the pen is ignored. 


Specifies the brush with which the path is to be filled. If Render- 
Mode is set to NO_DISPLAY or OPEN, the brush is ignored. 


Specifies the color with which the path is filled if BkMode is set 


to OPAQUE. 
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ENUMPAPERBINS 
Syntax short Escape(4DC, ENUMPAPERBINS, sizeof(int), /pNumBins, [pOutData) 


Return Value 


Comments 


This escape retrieves attribute information about a specified number of paper bins. The 
GETSETPAPERBINS escape retrieves the number of bins available on a printer. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpNumBins LPINT Points to an integer that specifies the number of bins 


for which information is to be retrieved. 


IpOutData LPSTR Points to a data structure to which information about 
the paper bins is copied. The size of the structure depends on the 
number of bins for which information was requested. See the fol- 
lowing “Comments” section for a description of this data 
structure. 


The return value specifies the outcome of the escape. It is 1 if the escape is successful; it is 
zero if the escape is not successful or not implemented. 


The data structure to which the /pOutData parameter points consists of two arrays. The 
first is an array of short integers containing the paper-bin identifier numbers in the follow- 
ing format: 


short BinList{LcBinMax] 


The number of integers in the array (cBinMax) is equal to the value pointed to by the 
IpNumBins parameter. 


The second array in the data structure to which /JpOutData points is an array of characters 
in the following format: 


char PaperNames[cBinMax]EcchBinName] 


The cBinMax value is equal to the value pointed to by the JpNumBins parameter; the 
cchBinName value is the length of each string (currently 24). 
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ENUMPAPERMETRICS 
Syntax short Escape(4DC, ENUMPAPERMETRICS, sizeof(int), pMode, IpOutData) 


This escape performs one of two functions according to the mode: 


= It determines the number of paper types supported and returns this value, which can 
then be used to allocate an array of RECT data structures. 


= It returns one or more RECT data structures that define the areas on the page that can 
receive an image. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

IpMode LPINT Points to an integer that specifies the mode for the 
escape. It can be one of the following values: 
Value Meaning 
0 The return value indicates how many 


RECT data structures are required to 
contain the information about the availa- 


ble paper types. 
1 The array of RECT structures to which 
[pOutData points is filled with the infor- 
mation. 
lpOutData LPRECT Points to an array of RECT data structures that re- 


turn all the areas that can receive an image. 


Return Value The return value is positive if successful, zero if the escape is not implemented, and nega- 
tive if an error occurred. 


EPSPRINTING 
Syntax short Escape(DC, EPSPRINTING, sizeof(BOOL), [pBool, NULL) 


This escape suppresses the output of the Windows PostScript header control section, which 
is about 7K. If an application uses this escape, no GDI calls are allowed. 
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EXT_DEVICE_CAPS 


Return Value 


Parameter 


hDC 
[pBool 


Type/Description 


HDC Identifies the device context. 


BOOL FAR * 


Points to a Boolean value indicating that 


downloading should be enabled (TRUE) or disabled (FALSE). 


The return value is positive if successful, zero if the escape is not implemented, and nega- 
tive if an error occurred. 


EXT_DEVICE_CAPS 
short Escape(ADC, EXT_DEVICE_CAPS, sizeof(int), /pIndex, IpCaps) 


Syntax 


This escape retrieves information about device-specific capabilities. It supplements the 
GetDeviceCaps function. 


Parameter 


hDC 
[pIndex 


Type/Description 


HDC Identifies the device context. 


LPINT Points to a short integer specifying the index of the capabil- 
ity to be retrieved. It can be any one of the following values: 


Value 


R2_CAPS (1) 


Meaning 


The /pCaps parameter indicates 
which of the 16 binary raster 
operations the device driver sup- 
ports. A bit will be set for each 
supported raster operation. For 
further information, see the 
description of the SetROP2 
function in Chapter 4, “Func- 
tions Directory,” in Reference, 
Volume 1. 


EXT_DEVICE_CAPS 


Parameter 


Type/Description 


Value 


PATTERN_CAPS (2) 


PATH_CAPS (3) 


POLYGON_CAPS (4) 


PATTERN_COLOR_CAPS (5) 
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Meaning 


The /pCaps parameter returns 
the maximum dimensions of a 
pattern brush bitmap. The low- 
order word of the capability 
value contains the maximum 
width of a pattern brush bitmap, 
and the high-order word con- 
tains the maximum height. 


The [pCaps parameter indicates 
whether the device is capable of 
creating paths using alternate 
and winding interiors, and 
whether the device can do ex- 
clusive or inclusive clipping to 
path interiors. The path capabili- 
ties are obtained using the 
logical OR operation on the fol- 
lowing values: 


PATH_ALTERNATE (1) 
PATH_WINDING (2) 
PATH_INCLUSIVE (4) 
PATH_EXCLUSIVE (8) 


The /pCaps parameter returns 
the maximum number of poly- 
gon points supported by the 
device. The capability value is 
an unsigned value specifying 
the maximum number of points. 


The /pCaps parameter indicates 
whether the device can convert 
monochrome pattern bitmaps to 
color. The capability value is 1 
if the device can do pattern bit- 
map color conversions, and 
zero if it cannot. 
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Parameter Type/Description 
Value Meaning 
R2_TEXT_CAPS (6) The /pCaps parameter indicates 


whether the device is capable of 
performing binary raster opera- 
tions on text. The low-order 
word of the capability value 
specifies which raster opera- 
tions are supported for text. A 
bit is set for each supported 
raster operation, as in the 
R2_CAPS escape. The high- 
order word specifies the type of 
text to which the raster capabili- 
ties apply. It is obtained by 
applying the logical OR opera- 
tion to the following values 
together: 


RASTER_TEXT (1) 
DEVICE_TEXT (2) 
VECTOR_TEXT (4) 


IpCaps DWORD FAR * Points to a 32-bit integer to which the capabili- 
ties will be copied. 


Return Value The return value is nonzero if the specified extended capability is supported, and zero if it 
is not. 

EXTTEXTOUT 

Syntax short Escape(4DC, EXTTEXTOUT, sizeof(EXTTEXT_ STRUCT), /pInData, NULL) 


This escape provides an efficient way for the application to call the GDI TextOut function 
when justification, letter spacing, and/or kerning are involved. 


This function is provided only for backward compatibility. New applications should use 
the GDI ExtTextOut function instead. 
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Return Value 


Comments 


Parameter Type/Description 
hDC HDC Identifies the device context. 
[pInData EXTTEXT_STRUCT FAR * Points to an EXTTEXT_STRUCT 


data structure that specifies the initial position, characters, and 
character widths of the string. See the following “Comments” section 
for more information on the EXTTEXT_STRUCT data structure. 


The return value specifies the outcome of the escape. It is 1 if the escape is successful; it is 
zero if the escape is not successful or not implemented. 


The EXTEXT_STRUCT data structure has the following format: 


typedef struct { 
WORD X; 
WORD Ns 
WORD FAR *lpText; 
WORD FAR *1lpWidths; 
} EXTTEXT_STRUCT; 


This structure has the following fields. 


Field Description 

Xx Specifies the x-coordinate of the upper-left corner of the string’s 
starting point. 

Y Specifies the y-coordinate of the upper-left corner of the string’s 
starting point. 

IpText Points to an array of cch character codes, where cch is the num- 
ber of bytes in the string (cch is also the number of words in the 
width array). 

IpWidths Points to an array of cch character widths to use when printing 


the string. The first character appears at (X,Y), the second at (X 
+ IpWidths[0],Y), the third at (X + IpWidths[0] + 
IpWidths[1], Y), and so on. These character widths are specified 
in the font units of the currently selected font. (The character 
widths will always be equal to device units unless the applica- 
tion has enabled relative character widths.) 


The units contained in the width array are specified as font units 
of the device. 
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FLUSHOUTPUT 


FLUSHOUTPUT 


Syntax 


Return Value 


short Escape(hDC, FLUSHOUTPUT, NULL, NULL, NULL) 


This escape clears all output from the device’s buffer. 
Parameter Type/Description 


hDC HDC Identifies the device context. 


The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is negative. 


GETCOLORTABLE 


Syntax 


Return Value 


short Escape(hDC, GETCOLORTABLE, sizeof(int), /p/ndex, lpColor) 


This escape retrieves an RGB color-table entry and copies it to the location specified by 
the /pColor parameter. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

IpIndex LPINT Points to a short-integer value that specifies the index 
of a color-table entry. Color-table indexes start at zero for the 
first table entry. 

IpColor DWORD FAR * Points to the long-integer value that will re- 


ceive the RGB color value for the given entry. 


The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is negative. 


GETEXTENDEDTEXTMETRICS 


Syntax 


short Escape(4DC, GETEXTENDEDTEXTMETRICS, sizeof(WORD), /pInData, 
[pOutData) 


This escape fills the buffer pointed to by the JpOutData parameter with the extended text 
metrics for the selected font. 


GETEXTENDEDTEXTMETRICS 
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Return Value 


Comments 


Parameter 


hDC 
IpInData 


lpOutData 


Type/Description 


HDC Identifies the device context. 


WORD FAR * Points to an unsigned 16-bit integer that speci- 
fies the number of bytes pointed to by the /pOutData parameter. 


EXTTEXTMETRIC FAR * 


Points to an EXTTEXT- 


METRIC data structure. See the following “Comments” section 


for a description of this data structure. 


The return value specifies the number of bytes copied to the buffer pointed to by the /pOut- 
Data parameter. This value will never exceed that specified in the nSize field pointed to by 
the /pInData parameter. The return value is zero if the escape fails or is not implemented. 


The /pOutData parameter points to an EXTTEXTMETRIC data structure which has the 
following format: 


typedef struc{ 


short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
WORD 

WORD 


JEXTTEXT 


The EXTTEXTMETRIC data structure has the following fields: 


etm 
etm 
etm 
etn 
etm 
etm 
etm 
etm 
etm 
et 

et 

etn 
etm 
etn 
et 
et 
etn 
et 
et 
etm 
et 
etm 
et 
etn 
etn 
et 


Size; 

PointSize; 

Orientation; 

asterHeight; 

inScale; 

axScale; 

asterUnits; 

CapHeight; 

XHeight; 

LowerCaseAscent; 
LowerCaseDescent; 

Slant; 

SuperScript; 

SubScript; 
SuperScriptSize; 
SubScriptSize; 
UnderlineOffset; 
UnderlineWidth; 
DoubleUpperUnderlineOffset; 
DoubleLowerUnderlineOffset; 
DoubleUpperUnderlineWidth; 
DoubleLowerUnderlineWidth; 
StrikeOutOffset; 
StrikeOutWidth; 

KernPairs; 

KernTracks; 

ETRIC; 
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Field 
etmSize 


etmPointSize 


etmOrientation 


etmMaster Height 


etmMinScale 


etmMaxScale 


GETEXTENDEDTEXTMETRICS 


Description 
Specifies the size of the structure in bytes. 


Specifies the nominal point size of this font 
in twips (twentieths of a point, or 1.440 
inch). This is the intended size of the font; 
the actual size may differ slightly depending 
on the resolution of the device. 


Specifies the orientation of the font. The et- 
mOrientation field may be any of the 
following values: 


Value Méaning 

0 Either orientation 
1 Portrait 

2. Landscape 


These values refer to the ability of this font 
to be placed on a page with the given orienta- 
tion. A portrait page has a height that is 
greater than its width. A landscape page has 
a width that is greater than its height. 


Specifies the font size in device units for 
which the values in this font’s extent table 
are exact. 


Specifies the minimum valid size for this 
font. The following equation illustrates how 
the minimum point size is determined: 


etmMinScale x 72 


smallest point size = 
P dfVertRes 


The value 72 represents the number of 
points per inch. The dfVertRes value is the 
number of dots per inch. 


Specifies the maximum valid size for this 
font. The following equation illustrates how 
the maximum point size is determined: 


etmMaxScale x 72 


largest point size = 
a dfVertRes 
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Field 


etmMaster Units 


etmCapHeight 


etmXHeight 


etmLower CaseAscent 


etmLowerCaseDescent 


etmSlant 


etmSuperScript 


etmSubScript 


etmSuperScriptSize 
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Description 


The value 72 represents the number of 
points per inch. The dfVertRes value is the 
number of dots per inch. 


Specifies the integer number of units per em 
where an em equals etmMasterHeight. That 
is, etmMaster Units is emtMasterHeight 
expressed in font units rather than device 
units. 


Specifies the height in font units of upper- 
case characters in the font. Typically, this is 
the height of the capital H. 


Specifies the height in font units of lower- 
case characters in the font. Typically, this is 
the height of the lowercase x. 


Specifies the distance in font units that the 
ascender of lowercase letters extends above 
the baseline. Typically, this is the height of 
the lowercase d. 


Specifies the distance in font units that the 
descender of lowercase letters extends below 
the baseline. Typically, this is specified for 
the descender of the lowercase p. 


Specifies for an italicized or slanted font the 
angle of the slant measured in tenths of a 
degree clockwise from the upright version of 
the font. 


Specifies in font units the recommended 
amount to offset superscript characters from 
the baseline. This is typically a negative 
value. 


Specifies in font units the recommended 
amount to offset subscript characters from 
the baseline. This is typically a positive 
value. 


Specifies in font units the recommended size 
of superscript characters for this font. 
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Field Description 


etmSubScriptSize Specifies in font units the recommended size 
of subscript characters for this font. 


etmUnderlineOffset Specifies in font units the offset downward 
from the baseline where the top of a single 
underline bar should appear. 


etmUnderlineWidth Specifies in font units the thickness of the 
underline bar. 


etmDouble Upper UnderlineOffset Specifies the offset in font units downward 
from the baseline where the top of the upper 
double underline bar should appear. 


etmDoubleLowerUnderlineOffset Specifies the offset in font units downward 
from the baseline where the top of the lower 
double underline bar should appear. 


etmDouble Upper UnderlineWidth Specifies in font units the thickness of the 
upper underline bar. 


etmDoubleLowerUnderline Width Specifies in font units the thickness of the 
lower underline bar. 


etmStrikeOutOffset Specifies in font units the offset upward 
from the baseline where the top of a strike- 
out bar should appear. 


etmStrikeOutWidth Specifies the thickness in font units of the 
strike-out bar. 


etmKernPairs Specifies the number of character kerning 
pairs defined for this font. An application 
can use this value to calculate the size of the 
pair-kern table returned by the 
GETPAIRKERNTABLE escape. It will 
not be greater than 512 kern pairs. 


etmKernTracks Specifies the number of kerning tracks de- 
fined for this font. An application can use 
this value to calculate the size of the track- 
kern table returned by the 
GETTRACKKERNTABLE escape. It will 
not be greater than 16 kern tracks. 
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The values returned in many of the fields of the EXTTEXTMETRIC structure are af- 
fected by whether relative character widths are enabled or disabled. For more information, 
see the description of ENABLERELATIVEWIDTHS escape earlier in this chapter. 


GETEXTENTTABLE 


Syntax 


Return Value 


Comments 


short Escape(hADC, GETEXTENTTABLE, sizeof(CHAR_RANGE_ STRUCT), 
IpInData, [pOutData) 


This escape retrieves the width (extent) of individual characters from a group of consecu- 
tive characters in the selected font’s character set. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpInData LPSTR Points toa CHAR_RANGE STRUCT data structure 


that defines the range of characters for which the width is to be re- 
trieved. See the following “Comments” section for more information 
on the CHAR_RANGE_STRUCT data structure. 


lpOutData LPINT Points to an array of short integers that receives the 
character widths. The size of the array must be at least (chLast — 
chFirst + 1). 


The return value specifies the outcome of the escape. It is 1 if the escape is successful, and 


zero if the escape is not successful. If the escape is not implemented, the return value is 
Zero. 


The /p/nData parameter points toa CHAR_RANGE_ STRUCT data structure that de- 
fines the range of characters for which the width is to be retrieved. The 
CHAR_RANGE_ STRUCT structure has the following format: 


typedef struct { 
BYTE chFirst; 
BYTE chLast; 

} CHAR_RANGE_STRUCT 
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This structure has the following fields: 


Field Description 


chFirst Specifies the character code of the first character whose width is 
to be retrieved. 


chLast Specifies the character code of the last character whose width is 
to be retrieved. 


The values retrieved are affected by whether relative character widths are enabled or dis- 
abled. For more information, see the ENABLERELATIVEWIDTHS escape, earlier in 
this chapter. 


GETFACENAME 
Syntax short Escape(hDC, GETFACENAME, NULL, NULL, /pFaceName) 


This escape retrieves the face name of the current physical font. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpFaceName LPSTR Points to a buffer of characters to receive the face 


name. This buffer must be at least 60 bytes in length. 


Return Value The return value is positive if the escape was successful, zero if the escape is not imple- 
mented, or negative if an error occurred. 


GETPAIRKERNTABLE 
Syntax short Escape(hDC, GETPAIRKERNTABLE, NULL, NULL, /pOutData) 


This escape fills the buffer pointed to by the /pOutData parameter with the character-pair 
kerning table for the selected font. 
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Return Value 


Comments 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpOutData KERNPAIR FAR * Points to an array of KERNPAIR data 


structures. This array must be large enough to accommodate the 
font’s entire character-pair kerning table. The number of 
character-kerning pairs in the font can be obtained from the 
EXTTEXTMETRIC data structure returned by the GETEX- 
TENDEDTEXTMETRICS escape. See the following 
“Comments” section for the format of the KERNPAIR data 
structure. 


The return value specifies the number of KERNPAIR structures copied to the buffer. This 
value is zero if the font does not have kerning pairs defined, the escape fails, or is not im- 
plemented. 


The KERNPAIR data structure has the following format: 


typedef struc { 


union { 
BYTE each [2]; /* UNION: ‘each' and 'both' 
share the same memory */ 
WORD both; 
} kpPair; 
short kpKernAmount ; 
} KERNPAIR; 


The KERNPAIR structure contains the following fields: 


Field Description 

kpPair.each[0] Specifies the character code for the first character in the kerning 
pair. 

kpPair.each[1] Specifies the character code for the second character in the kern- 
ing pair. 

kpPair.both Specifies a WORD in which the first character in the kerning 
pair is in the low-order byte and the second character is in the 
high-order byte. 

kpKernAmount Specifies the signed amount that this pair will be kerned if they 


appear side by side in the same font and size. This value is typi- 
cally negative since pair-kerning usually results in two 
characters being set more tightly than normal. 
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The array of KERNPAIR structures is sorted in increasing order by the kpPair.both field. 


The values returned in the KERNPAJR structures are affected by whether relative 


character widths are enabled or disabled. For more information, see the description of the 
ENABLERELATIVEWIDTHS escape earlier in this chapter. 


GETPHYSPAGESIZE 
Syntax short Escape(hDC, GETPHYSPAGESIZE, NULL, NULL, /[pDimensions) 


This escape retrieves the physical page size and copies it to the location pointed to by the 
[pDimensions parameter. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpDimensions LPPOINT Points to a POINT data structure that will receive 


the physical page dimensions. The x field of the POINT data 
structure receives the horizontal size in device units, and the y 
field receives the vertical size in device units. 


Return Value The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is negative. 


GETPRINTINGOFFSET 
Syntax short Escape(hDC, GETPRINTINGOFFSET, NULL, NULL, /pOffset) 


This escape retrieves the offset from the upper-left corner of the physical page where the 


actual printing or drawing begins. This escape is generally not useful for devices that allow 
the user to set the origin of the printable area directly. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
lpOffset LPPOINT Points to a POINT structure that will receive the 


printing offset. The x field of the POINT structure receives the 
horizontal coordinate of the printing offset in device units, and 


the y field receives the vertical coordinate of the printing offset 
in device units. 
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Return Value The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is negative. 


GETSCALINGFACTOR 
Syntax short Escape(hDC, GETSCALINGFACTOR, NULL, NULL, /pFactors) 


This escape retrieves the scaling factors for the x- and y-axes of a printing device. For each 
scaling factor, the escape copies an exponent of 2 to the location pointed to by the /pFac- 
tors parameter. For example, the value 3 is copied to /pFactors if the scaling factor is 8. 


Scaling factors are used by printing devices that support graphics at a smaller resolution 


than text. 

Parameter Type/Description 

hDC HDC Identifies the device context. 

IpFactors LPPOINT Points to the POINT data structure that will re- 


ceive the scaling factor. The x field of the POINT structure 
receives the scaling factor for the x-axis, and the y field receives 
the scaling factor for the y-axis. 


Return Value The return value specifies the outcome of the escape. It is positive if the escape is success- 


ful. Otherwise, it is negative. 


GETSETPAPERBINS 
Syntax short Escape(hDC, GETSETPAPERBINS, nCount, IpInData, lpOutData) 
This escape retrieves the number of paper bins available on a printer and sets the current 


paper bin. See the following “Comments” section for more information on the actions per- 
formed by this escape. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

nCount int Specifies the number of bytes pointed to by the /p/nData 
parameter. 

IpInData BinInfo FAR * Points to a BinInfo data structure that speci- 


fies the new paper bin. It may be set to NULL. 
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Comments 


Parameter Type/Description 


[pOutData BinInfo FAR * Points to a BinInfo data structure that con- 
tains information about the current or previous paper bin and the 
number of bins available. 


There are three possible actions for this escape, depending on the values passed in the /pJn- 
Data and [pOutData parameters: 


IpInData IpOutData Action 


NULL BinInfo Retrieves the number of bins and the number of the current bin. 


BinInfo BinInfo Sets the current bin to the number specified in the BinNumber field 
of the data structure to which /p/nData points and retrieves the num- 
ber of the previous bin. 


BinInfo NULL Sets the current bin to the number specified in the BinNumber field 
of the data structure to which /p/nData points. 


The BinInfo data structure has the following format: 


typedef struct{ 
DWORD BinNumber; 
DWORD NbrofBins; 


DWORD Reserved; 

DWORD Reserved; 

DWORD Reserved; 

DWORD Reserved; 
} BinInfo; 


The BinInfo structure has the following fields: 


Field Description 
BinNumber Identifies the current or previous paper bin. 
NbrofBins Specifies the number of paper bins available. 


When setting a new bin, the setting does not take effect until a new device context is 
created (without initialization data). The setting will take immediate effect if the high bit of 
the bin number is set, so that the next page printed will come from the new bin. For ex- 
ample, 0x8001 uses the second bin immediately whenever 0x0001 sets the same bin as the 
default for later print jobs. 
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In general, only the immediate-selection form should be used by applications. Setting the 
bin for future print jobs is supported for backward compatibility to an earlier form of this 


escape which appeared in some versions of HP’s Page Control Language (PCL) and Post- 
Script. 


GETSETPAPERMETRICS 


Syntax 


Return Value 


short Escape(4DC, GETSETPAPERMETRICS, sizeof(RECT), /pNewPaper, 
lpPrevPaper) 


This escape sets the paper type according to the given paper metrics information. It also re- 
trieves the current printer’s paper metrics information. 


This escape expects a RECT data structure representing the imageable area of the physical 
page and assumes the origin is in the upper-left corner. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
lpNewPaper LPRECT Points to a RECT data structure that defines the 


new imageable area. 


[pPrevPaper LPRECT Points to a RECT data structure that receives the 
previous imageable area. 


The return value is positive if successful, zero if the escape is not implemented, and nega- 
tive if an error occurs. 


Comments This escape is provided only for backward compatibility. New applications should use the 
GDI DeviceCapabilities and ExtDeviceMode functions instead. 

GETSETPAPERORIENT 

Syntax 


short Escape(4DC, GETSETPAPERORIENT, nCount, lpInData, NULL) 


This escape returns or sets the current paper orientation. 


Parameter Type/Description 


hDC HDC Identifies the device context. 
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Parameter Type/Description 

nCount Specifies the number of bytes pointed to by the /p/nData para- 
meter. 

[pInData ORIENT FAR * Points to an ORIENT data structure that 


specifies the new paper orientation. See the following “Com- 
ments” section for a description of this data structure. It may be 
set to NULL, in which case the GETSETPAPERORIENT 
escape returns the current paper orientation. 


Return Value The return value specifies the current orientation if Jp[nData is NULL; otherwise, it is the 
previous orientation. The return value is —1 if the escape failed. 


Commenis This escape is provided only for backward compatibility. New applications should use the 
GDI DeviceCapabilities and ExtDeviceMode functions instead. 


The ORIENT data structure has the following format: 


typedef struct{ 
DWORD Orientation; 
DWORD Reserved; 
DWORD Reserved; 
DWORD Reserved; 
DWORD Reserved; 

} ORIENT; 


The Orientation field can be either of these values: 


Value Meaning 
1 The new orientation is portrait. 
2 The new orientation is landscape. 


This escape is also known as GETSETPAPERORIENTATION. 


GETSETSCREENPARAMS 
Syntax short Escape(4DC, GETSETSCREENPARAMS, sizeof(SCREENPARAMS), 
IpInData, IpOutData) 


This escape retrieves or sets the current screen information for rendering halftones. 
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Parameter Type/Description 

hDC HDC Identifies the device context. 

IpInData SCREENPARAMS FAR * Points toa SCREENPARAMS 
data structure that contains the new screen information. This 
parameter may be NULL. 

lpOutData SCREENPARAMS FAR * Points toa SCREENPARAMS 
data structure that retrieves the previous screen information. 

This parameter may be NULL. 
Return Value The return value specifies the outcome of the escape. It is positive if the escape is success- 


ful. Otherwise, it is negative. 

Comments This escape affects how device-independent bitmaps (DIBs) are rendered and how color 
objects are filled. 
The SCREENPARAMS data structure has the following format: 


typedef struct { 


int angle; 
int frequency; 
DWORD types; 

} SCREENPARAMS; 


The SCREENPARAMS structure has the following fields: 


Field Description 

angle Specifies in degrees the angle of the halftone screen. 
frequency Specifies in dots per inch of the screen frequency. 

types Is a mask containing bits which indicate the type of screen cell. 


If a pointer to this structure is passed as the /p/nData parameter, 
only one bit may be set. If the pOutData parameter contains a 
pointer to this structure, when the escape returns, the types field 
will have a bit set for each type supported by the printer driver. 
Acceptable bit values are: 


a DIAMOND 
a DOT 
a ELLIPSE 
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a LINE 


GETTECHNOLOGY 
Syntax short Escape(hDC, GETTECHNOLOGY, NULL, NULL, IpTechnology) 


This escape retrieves the general technology type for a printer, thereby allowing an applica- 
tion to perform technology-specific actions. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

IpTechnology LPSTR Points to a buffer to which the driver copies a null-ter- 
minated string containing the printer technology type, such as 
“PostScript.” 


Return Value The return value specifies the outcome of the escape. It is 1 if the escape is successful, and 


is zero if the escape is not successful or is not implemented. 


GETTRACKKERNTABLE 
Syntax short Escape(hDC, GETTRACKKERNTABLE, NULL, NULL, /pOutData) 


This escape fills the buffer pointed to by the /pOutData parameter with the track-kerning 
table for the currently selected font. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
[pOutdata KERNTRACK FAR * Points to an array of KERNTRACK 


structures. This array must be large enough to accommodate all 
the font’s kerning tracks. The number of tracks in the font can be 
obtained from the EXTTEXTMETRIC structure returned by 
the GETEXTENDEDTEXTMETRICS escape. See the follow- 


ing “Comments” section for the format of the KERNTRACK 
data structure. 
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Return Value 


Comments 


The return value specifies the number of KERNTRACK structures copied to the buffer. 
This value is zero if the font does not have kerning tracks defined, or if the escape fails or 
is not implemented. 


The KERNTRACK data structure has the following format: 


typedef struct { 


short ktDegree; 
short ktMinSize; 
short ktMinAmount; 
short ktMaxSize; 
short ktMaxAmount ; 
} KERNTRACK; 


The KERNTRACK structure contains the following fields: 


Field Description 


ktDegree Specifies the amount of track kerning. Increasingly negative 
values represent tighter track kerning, and increasingly positive 
values represent looser track kerning. 


ktMinSize Specifies in device units the minimum font size for which linear 
track kerning applies. 


ktMinA mount Specifies in font units the amount of track kerning to apply to 
font sizes less than or equal to the size specified by the ktMin- 
Size field. 


ktMaxSize Specifies in device units the maximum font size for which linear 
track kerning applies. 


ktMaxAmount Specifies in font units the amount of track kerning to apply to 
font sizes greater than or equal to the size specified by the 
ktMaxSize field. 


Between the ktMinSize and ktMaxSize font sizes, track kerning is a linear function from 
ktMinAmount to ktMaxAmount. The values returned in the KERNTRACK structures 
are affected by whether relative character widths are enabled or disabled. For more infor- 
mation, see the description of the ENABLERELATIVEWIDTHS escape earlier in this 
chapter. 
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GETVECTORBRUSHSIZE 
Syntax short Escape(4DC, GETVECTORBRUSHSIZE, sizeof(LOGBRUSH), /p/nData, 
[pOutData) 


This escape retrieves in device units the size of a plotter pen used to fill closed figures. 


GDI uses this information to prevent the plotter pen from writing over the borders of the 
figure when filling closed figures. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpInData LOGBRUSH FAR * Points toa LOGBRUSH data structure 


that specifies the brush for which data are to be returned. 


IpOutData LPPOINT Points to a POINT data structure that contains in 
its second word the width of the pen in device units. 


Return Value The return value specifies the outcome of the escape. It is 1 if the escape is successful; it is 
zero if the escape is not successful or is not implemented. 


GETVECTORPENSIZE 
Syntax short Escape(4DC, GETVECTORPENSIZE, sizeof(LOGPEN), /p/nData, 
[pOutData) 


This escape retrieves the size in device units of a plotter pen. GDI uses this information to 
prevent hatched brush patterns from overwriting the border of a closed figure. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpInData LOGPEN FAR * Points toa LOGPEN data structure that 


specifies the pen for which the width is to be retrieved. 


IpOutData LPPOINT Points to a POINT data structure that contains in 
its second word the width of the pen in device units. 


Return Value The return value specifies the outcome of the escape. It is 1 if the escape is successful; it is 
zero if the escape is not successful or if it is not implemented. 
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MFCOMMENT 
Syntax 


Return Value 


BOOL  Escape(hDC, MFCOMMENT, nCount, IpComment, NULL) 


This escape adds a comment to a metafile. 


Parameter Type/Description 


hDC HDC Identifies the device context for the device on which the 
metafile appears. 


nCount short Specifies the number of characters in the string pointed 
to by the /p>Comment parameter. 


IpComment LPSTR Points to a null-terminated string that contains the 
comment that will appear in the metafile. 


The return value specifies the outcome of the escape. It is —1 if an error such as insufficient 
memory or an invalid port specification occurs. Otherwise, it is positive. 


NEWFRAME 
Syntax 


Return Value 


short Escape(4DC, NEWFRAME, NULL, NULL, NULL) 


This escape informs the device that the application has finished writing to a page. This 
escape is typically used with a printer to direct the device driver to advance to a new page. 


Parameter Type/Description 


hDC HDC Identifies the device context. 


The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is one of the following values: 
Value Meaning 


SP_APPABORT Job was terminated because the application’s abort func- 
tion returned zero. 


SP_ERROR General error. 
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NEXTBAND 


Comments 


Value Meaning 


SP_OUTOFDISK Not enough disk space is currently available for spool- 
ing, and no more space will become available. 


SP_OUTOFMEMORY Not enough memory is available for spooling. 
SP_USERABORT User terminated the job through the Print Manager. 


Do not use the NEXTBAND escape with NEWFRAME. For banding drivers, GDI re- 
plays a metafile to the printer, simulating a sequence of NEXTBAND escapes. 


The NEWFRAME escape restores the default values of the device context. Consequently, 
if a font other than the default font is selected when the application calls the NEW- 
FRAME escape, the application must select the font again following the NEWFRAME 
escape. 


NEXTBAND 


Syntax 


Return Value 


short Escape(4DC, NEXTBAND, NULL, NULL, /[pBandRect) 


This escape informs the device driver that the application has finished writing to a band, 
causing the device driver to send the band to the Print Manager and return the coordinates 
of the next band. Applications that process banding themselves use this escape. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
[pBandRect LPRECT Points to the RECT data structure that will receive 


the next band coordinates. The device driver copies the device 
coordinates of the next band into this structure. 


The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is one of the following values: 
Value Meaning 


SP_APPABORT Job was terminated because the application’s abort func- 
tion returned zero. 


SP_ERROR General error. 
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Value Meaning 
SP_OUTOFDISK Not enough disk space is currently available for spool- 
ing, and no more space will become available. 
SP_OUTOFMEMORY Not enough memory is available for spooling. 
SP_USERABORT User terminated the job through the Print Manager. 
Commenis The NEXTBAND escape sets the band rectangle to the empty rectangle when printing 
reaches the end of a page. 
Do not use the NEWFRAME escape with NEXTBAND. 
PASSTHROUGH 
Syntax short Escape(hDC, PASSTHROUGH, nCount, IpInData, NULL) 


Return Value 


Comments 


This escape allows the application to send data directly to the printer, bypassing the stand- 
ard print-driver code. 


NOTE To use this escape, an application must have thorough knowledge of how the particular printer 
Operates. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
nCount short Specifies the number of bytes to which the /p/nData 


parameter points. 


[pInData LPSTR Points to a structure whose first word (16 bits) con- 
tains the number of bytes of input data. The remaining bytes of 
the structure contain the data itself. 


The return value specifies the number of bytes transferred to the printer if the escape is 
successful. It is less than zero if the escape is not implemented, and less than or equal to 
zero if the escape is not successful. 


There may be restrictions on the kinds of device data an application can send to the device 
without interfering with the operation of the driver. In general, applications must avoid re- 
setting the printer or causing the page to be printed. 
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QUERYESCSUPPORT 


It is strongly recommended that applications not perform functions that consume printer 
memory, such as downloading a font or a macro. 


An application can avoid corrupting its data stream when issuing multiple, consecutive 
PASSTHROUGH escapes if it does not access the printer any other way during the 
sequence. 


QUERYESCSUPPORT 


Syntax 


Return Value 


short Escape(hADC, QUERYESCSUPPORT, sizeof(int), /pEscNum, NULL) 


This escape determines whether a particular escape is implemented by the device driver. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpEscNum LPINT Points to a short-integer value that specifies the 


escape function to be checked. 


The return value specifies whether a particular escape is implemented. It is nonzero for im- 
plemented escape functions. Otherwise, it is zero. 


If the IpEscNum parameter is set to DRAWPATTERNRECT, the return value is one of the 
following: 


Value Meaning 

0 DRAWPATTERNRECT is not implemented. 

1 DRAWPATTERNRECT is implemented for a printer other than 
the HP LaserJet IIP; this printer supports white rules. 

2 DRAWPATTERNRECT is implemented for the HP LaserJet ITP. 


RESTORE_CTM 


Syntax 


short Escape(hDC, RESTORE_CTM, NULL, NULL, NULL) 
This escape restores the previously saved current transformation matrix. 


The current transformation matrix controls the manner in which coordinates are translated, 
rotated, and scaled by the device. By using matrices, an application can combine these 
operations in any order to produce the desired mapping for a particular picture. 
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Parameter Type/Description 
hDC HDC Identifies the device context. 
Return Value The return value specifies the number of SAVE_CTM escape calls without a correspond- 


ing RESTORE_CTM call. If the escape is unsuccessful, the return value is —1. 


Commenis Applications should not make any assumptions about the initial contents of the current 
transformation matrix. 


This escape uses a matrix specification based on the Microsoft OS/2 Presentation Manager 
graphics programming interface (GPI) model, which is an integer-coordinate system simi- 
lar to the system which GDI uses. 


SAVE_CTM 
Syntax short Escape(hDC, SAVE_CTM, NULL, NULL, NULL) 
This escape saves the current transformation matrix. 


The current transformation matrix controls the manner in which coordinates are translated, 
rotated, and scaled by the device. By using matrices, an application can combine these 
operations in any order to produce the desired mapping for a particular picture. 


An application can restore the matrix by using the RESTORE_CTM escape. 


An application typically saves the current transformation matrix before changing it. This al- 
lows the application to restore the previous state upon completion of a particular operation. 


Parameter Type/Description 


hDC HDC Identifies the device context. 


Return Value The return value specifies the number of SAVE_CTM escape calls without a correspond- 
ing RESTORE_CTM call. The return value is zero if the escape was unsuccessful. 


Comments Applications should not make any assumptions about the initial contents of the current 
transformation matrix. 


Applications are expected to restore the contents of the current transformation matrix. 


This escape uses a matrix specification based on the OS/2 Presentation Manager graphics 
programming interface (GPI) model, which is an integer-coordinate system similar to the 
system that GDI uses. 
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SELECTPAPERSOURCE 


This escape has been superseded by the GETSETPAPERBINS escape and is provided 
only for backward compatibility. New applications should use the GETSETPAPERBINS 
escape instead. 


SETABORTPROC 
Syntax short Escape(hDC, SETABORTPROC, NULL, pAbortF unc, NULL) 


This escape sets the abort function for the print job. 


If an application is to allow the print job to be canceled during spooling, it must set the 
abort function before the print job is started with the STARTDOC escape. Print Manager 
calls the abort function during spooling to allow the application to cancel the print job or 
to process out-of-disk-space conditions. If no abort function is set, the print job will fail if 
there is not enough disk space for spooling. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpAbortFunc FARPROC Points to the application-supplied abort function. 


See the following “Comments” section for details. 


Return Value The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is negative. 


Comments The address passed as the /pAbortFunc parameter must be created by using the Make- 
ProcInstance function. 


The callback function must use the Pascal calling convention and must be declared FAR. 
The abort function must have the following form: 


Callback Function short FAR PASCAL AbortFunc(hPr, code) 
HDC hPr; 
short code; 


AbortF unc is a placeholder for the application-supplied function name. The actual name 
must be exported by including it in an EXPORTS statement in the application’s module- 
definition file. 


SETALLJUSTVALUES 
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Parameter Description 
hPr Identifies the device context. 
code 


Specifies whether an error has occurred. It is zero if no error has 
occurred. It is SP_LOUTOFDISK if Print Manager is currently 


out of disk space and more disk space will become available if 
the application waits. 


If code is SP_LOUTOFDISK, the application does not have to 
abort the print job. If it does not, it must yield to Print Manager 
by calling the PeekMessage or GetMessage function. 


Return Value 


The return value should be nonzero if the print job is to continue, and zero if it is canceled. 


SETALLJUSTVALUES 


Syntax 


Return Value 


Comments 


short Escape(hDC, SETALLJUSTVALUES, sizeof(JUST_VALUE_STRUCT), 
IpInData, NULL) 


This escape sets all of the text-justification values that are used for text output. 


Text justification is the process of inserting extra pixels among break characters in a line of 
text. The blank character is normally used as a break character. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpInData JUST_VALUE_ STRUCT FAR * Points toa 


JUST_VALUE_ STRUCT data structure that defines the text- 
justification values. See the following “Comments” section for 


more information on the JUST_VALUE_STRUCT data struc- 
ture. 


The return value specifies the outcome of the escape. It is 1 if the escape is successful. 
Otherwise, it is zero. 


The /pinData parameter points to a JUST_VALUE_STRUCT data structure that de- 


scribes the text-justification values used for text output. The JUST_VALUE_STRUCT 
structure has the following format: 
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typedef struct { 
short nCharExtra; 
WORD nCharCount; 
short nBreakExtra; 
WORD nBreakCount; 
} JUST_VALUE_STRUCT; 


This structure has the following fields: 


Field Description 

nCharExtra Specifies the total extra space (in font units) that must be dis- 
tributed over nCharCount characters. 

nCharCount Specifies the number of characters over which nCharExtra is 
distributed. 

nBreakExtra Specifies the total extra space (in font units) that is distributed 


over nBreakCount characters. 


nBreakCount Specifies the number of break characters over which nBreak- 
Extra is distributed. 


The units used for nCharExtra and nBreakExtra are the font units of the device and are 
dependent on whether relative character widths were enabled with the ENABLE- 
RELATIVEWIDTHS escape. 


The values set with this escape apply to subsequent calls to the TextOut function. The 
driver stops distributing the extra space specified in the nCharExtra field when it has out- 
put the number of characters specified in the nCharCount field. Likewise, it stops dis- 
tributing the space specified by the nBreakExtra field when it has output the number of 
characters specified by the nBreakCount field. A call on the same string to the GetText- 
Extent function made immediately after the call to the TextOut function will be processed 
in the same manner. 


To re-enable justification with the SetTextJustification and SetTextCharacterExtra func- 
tions, an application should call the SETALLJUSTVALUES escape and set the nChar- 
Extra and nBreakExtra fields to zero. 


SET_ARC_DIRECTION 
Syntax short Escape(hDC, SET_ARC_DIRECTION, sizeof(int), /pDirection, NULL) 


This escape specifies the direction in which elliptical arcs are drawn using the GDI Are 
function. 
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Return Value 


Comments 


SET_BACKGROUND_COLOR 


Syntax 


By convention, elliptical arcs are drawn counterclockwise by GDI. This escape lets an 
application draw paths containing arcs drawn clockwise. 


Parameter 


hDC 


[pDirection 


Type/Description 
HDC Identifies the device context. 


LPINT Points to a short integer specifying the arc direction. It 
can be either of the following values: 


a COUNTERCLOCKWISE (0) 
a CLOCKWISE (1) 


The return value is the previous arc direction. 


This escape maps to PostScript language elements and is intended for PostScript line dev- 


ices. 


short Escape(hDC, SET_ BACKGROUND COLOR, nCount, IpNewColor, 


IpOldColor) 


This escape sets and retrieves the current background color for the device. 


The background color is the color of the display surface before an application draws any- 
thing on the device. This escape is particularly useful for color printers and film recorders. 


This escape should be sent before the application draws anything on the current page. 


Parameter 
hDC 


nCount 


IpNewColor 


[pOldColor 


Type/Description 
HDC Identifies the device context. 


int Specifies the number of bytes pointed to by the /JpNew- 
Color parameter. 


DWORD FAR * Points to a 32-bit integer specifying the 
desired background color. This parameter can be NULL if the 
application is merely retrieving the current background color. 


DWORD FAR * Points to a 32-bit integer which receives the 
previous background color. This parameter can be NULL if the 
application does not use the previous background color. 
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SET_BOUNDS 
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Return Value 


The return value is TRUE if the escape was successful and FALSE if it was unsuccessful. 


Commenis The default background color is white. 
The background color is reset to the default when the device driver receives an ENDDOC 
or ABORTDOC escape. 

SET_BOUNDS 

Syntax short Escape(hDC, SET_BOUNDS, sizeof(RECT), /p/nData, NULL) 


Return Value 


Comments 


This escape sets the bounding rectangle for the picture being produced by the device driver 
supporting the given device context. It is used when creating images in a file format such 
as Encapsulated PostScript (EPS) and Hewlett-Packard Graphics Language (HPGL) for 
which there is a device driver. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

[pInData LPRECT Points to a RECT data structure that specifies in 
device coordinates a rectangle that bounds the image to be out- 
put. 


The return value is TRUE if the escape was successful; otherwise, the return value is 
FALSE. 


An application should issue this escape before each page in the image. For single-page im- 
ages, this escape should be issued immediately before the STARTDOC escape. 


When an application uses coordinate-transformation escapes, device drivers may not per- 
form bounding box calculations correctly. When an application uses the SET_BOUNDS 
escape, the driver does not have to calculate the bounding box. 


Applications should always use this escape to ensure support for the Encapsulated Post- 
Script (EPS) printing capabilities that will be built into future PostScript drivers. 
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SETCOLORTABLE 


Syntax 


Return Value 


Comments 


short Escape(hDC, SETCOLORTABLE, sizeof(COLORTABLE_STRUCT), 
IpInData, IpColor) 


This escape sets an RGB color-table entry. If the device cannot supply the exact color, the 
function sets the entry to the closest possible approximation of the color. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
[pInData COLORTABLE_ STRUCT FAR * Points toa 


COLORTABLE_STRUCT data structure that contains the 
index and RGB value of the color-table entry. See the following 
“Comments” section for more information on the 
COLORTABLE_ STRUCT data structure. 


IpColor DWORD FAR * Points to the long-integer value that is to re- 
ceive the RGB color value selected by the device driver to 
represent the requested color value. 


The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is negative. 


The COLORTABLE_STRUCT data structure has the following format: 
typedef struct { 

WORD = Index; 

DWORD rgb; 
} COLORTABLE_STRUCT; 


This structure has the following fields: 


Field Description 

Index Specifies the color-table index. Color-table entries start at zero 
for the first entry. 

rgb Specifies the desired RGB color value. 


A device’s color table is a shared resource; changing the system display color for one 
window changes it for all windows. Only applications developers who have a thorough 
knowledge of the display driver should use this escape. 


The SETCOLORTABLE escape has no effect on devices with fixed color tables. 
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SETCOPYCOUNT 


This escape is intended for use by both printer and display drivers. However, the EGA and 
VGA color drivers do not support it. 


This escape changes the palette used by the display driver. However, since the driver’s 
color-mapping algorithms will probably no longer work with a different palette, an exten- 
sion has been added to this function. 


If the color index pointed to by the /p/nData parameter is OXFFFF, the driver is to leave all 
color-mapping functionality to the calling application. The application must use the proper 
color-mapping algorithm and take responsibility for passing the correctly mapped physical 
color to the driver (instead of the logical RGB color) in such device-driver functions as 
RealizeObject and ColorInfo. 


For example, if the device supports 256 colors with palette indexes of 0 through 255, the 
application would determine which index contains the color that it wants to use in a certain 
brush. It would then pass this index in the low-order byte of the DWORD logical color 
passed to the RealizeObject device-driver function. The driver would then use this color 
exactly as passed instead of performing its usual color-mapping algorithm. If the applica- 
tion wants to reactivate the driver’s color-mapping algorithm (that is, if it restores the origi- 
nal palette when switching from its window context), then the color index pointed to by 
IpInData should be OxFFFE. 


SETCOPYCOUNT 


Syntax 


Return Value 


short Escape(iDC, SETCOPYCOUNT, sizeof(int), /pNumCopies, [pActualCopies) 


This escape specifies the number of uncollated copies of each page that the printer is to 
print. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpNumCopies LPINT Points to a short-integer value that contains the num- 


ber of uncollated copies to be printed. 


IpActualCopies LPINT Points to a short-integer value that will receive the 
number of copies to be printed. This may be less than the num- 
ber requested if the requested number is greater than the device’s 
maximum copy count. 


The return value specifies the outcome of the escape. It is 1 if the escape is successful; it is 
zero if the escape is not successful. If the escape is not implemented, the return value is 
zero. 
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SETKERNTRACK 


Syntax 


Return Value 


Comments 


short Escape(hDC, SETKERNTRACK, sizeof(int), /pNewTrack, lpOldTrack) 


This escape specifies which kerning track to use for drivers that support automatic track 
kerning. A kerning track of zero disables automatic track kerning. 


When track kerning is enabled, the driver will automatically kern all characters according 
to the specified track. The driver will reflect this kerning both on the printer and in Get- 
TextExtent function calls. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
[pNewTrack LPINT Points to a short-integer value that specifies the kern- 


ing track to use. A value of zero disables this feature. Values in 
the range 1 to nKernTracks correspond to positions in the track- 
kerning table (using 1 as the first item in the table). For more 
information, see the description of the EXTTEXTMETRIC 
structure provided under the description of the GETEXTEN- 
DEDTEXTMETRICS escape. 


IpOldTrack LPINT Points to a short-integer value that will receive the 
previous kerning track. 


The return value specifies the outcome of the escape. It is 1 if the escape is successful; it is 
zero if the escape is not successful or not implemented. 


Automatic track kerning is disabled by default. 


A driver does not have to support the ENABLEPAIRKERNING escape just because it 
supplies the track-kerning table to the application by using the GETTRACKKERN- 
TABLE escape. In the case where GETTRACKKERNTABLE is supported but the SET- 
KERNTRACK escape is not, the application must properly space the characters on the 
output device. 


12-51 SETLINECAP 
SETLINECAP 
Syntax short Escape(hDC, SETLINECAP, sizeof(int), [pNewCap, lpOldCap) 


Return Value 


Comments 


This escape sets the line end cap. 


A line end cap is that portion of a line segment that appears on either end of the segment. 
The cap may be square or circular. It can extend past, or remain flush with the specified 
segment end points. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

lpNewCap LPINT Points to a short-integer value that specifies the end-cap 
type. The possible values and their meanings are given in the follow- 
ing list: 

Value Meaning 

-1 Line segments are drawn by using the default GDI 
end cap. 

0 Line segments are drawn with a squared end point 
that does not project past the specified segment 
length. 

1 Line segments are drawn with a rounded end 


point; the diameter of this semicircular arc is equal 
to the line width. 


2 Line segments are drawn with a squared end point 
that projects past the specified segment length. 
The projection is equal to half the line width. 


IpOldCap LPINT Points to a short-integer value that specifies the previous 
end-cap setting. 


The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is negative. 


The interpretation of this escape varies with page-description languages (PDLs). Consult 
the PDL documentation for its exact meaning. 


This escape is also known as SETENDCAP. 


SETLINEJOIN 


12-52 


SETLINEJOIN 
Syntax 


Return Value 


Comments 


short Escape(hDC, SETLINEJOIN, sizeof(int), /pNewJoin, IpOldJoin) 


This escape specifies how a device driver will join two intersecting line segments. The 
intersection can form a rounded, squared, or mitered corner. 


Parameter 


hDC 
[pNewJoin 


IpOldJoin 


Type/Description 


HDC 


Identifies the device context. 


LPINT Points to a short-integer value that specifies the type of 
intersection. The possible values and their meanings are given in the 


following list: 


Value 


-l 


Meaning 


Line segments are joined by using the default GDI 
setting. 


Line segments are joined with a mitered corner; 
the outer edges of the lines extend until they meet 
at an angle. This is referred to as a miter join. 


Line segments are joined with a rounded corner; a 
semicircular arc with a diameter equal to the line 
width is drawn around the point where the lines 
meet. This is referred to as a round join. 


Line segments are joined with a squared end point; 
the outer edges of the lines are not extended. This 
is referred to as a bevel join. 


LPINT Points to a short-integer value that specifies the previous 


line join setting. 


The return value specifies the outcome of the escape. It is positive if the escape is success- 


ful. Otherwise, it is negative. 


The interpretation of this escape varies with page-description languages (PDLs). Consult 
the PDL documentation for its exact meaning. 


If an application specifies a miter join but the angle of intersection is too small, the device 
driver ignores the miter setting and uses a bevel join instead. 
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SETMITERLIMIT 
Syntax short Escape(hDC, SETMITERLIMIT, sizeof(int), jp>NewMiter, lpOldMiter) 


Return Value 


Comments 


This escape sets the miter limit for a device. The miter limit controls the angle at which a 
device driver replaces a miter join with a bevel join. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
nCount short Specifies the number of bytes to which the IpNewMiter 


parameter points. 


[pNewMiter LPINT Points to a short-integer value that specifies the 
desired miter limit. Only values greater than or equal to —1 are 
valid. If this value is —1, the driver will use the default GDI 
miter limit. 


lpOldMiter LPINT Points to a short-integer value that specifies the pre- 
vious miter-limit setting. 


The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is negative. 


The miter limit is defined as follows: 


miter length _ 1 
line width ~ sin (x/2) 


X is the angle of the line join in radians. 


The interpretation of this escape varies with page-description languages (PDLs). Consult 
the PDL documentation for its exact meaning. 


SET_POLY_MODE 


Syntax 


short Escape(hDC, SET_POLY_MODE, sizeof(int), /pMode, NULL) 


This escape sets the poly mode for the device driver. The poly mode is a state variable indi- 
cating how to interpret calls to the GDI Polygon and Polyline functions. 


The SET_POLY_MODE escape enables a device driver to draw shapes (such as Bezier 
curves) not supported directly by GDI. This permits applications that draw complex curves 
to send the curve description directly to a device without having to simulate the curve as a 
polygon with a large number of points. 


SET_POLY_MODE 
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Parameter 


hDC 
IpMode 


Type/Description 
HDC Identifies the device context. 


LPINT Points to a short integer specifying the desired poly 
mode. The poly mode is a state variable indicating how points in 
Polygon or Polyline function calls should be interpreted. All 
device drivers are not required to support all possible modes. A 
device driver returns zero if it does not support the specified 
mode. The /pMode parameter may be one of the following values: 


Value Meaning 

PM_POLYLINE (1) The points define a conventional poly- 
gon or polyline. 

PM_BEZIER (2) The points define a sequence of 4- 


point Bezier spline curves. The first 
curve passes through the first four 
points, with the first and fourth points 
as end points, and the second and third 
points as control points. Each sub- 
sequent curve in the sequence has the 
end point of the previous curve as its 
start point, the next two points as con- 
trol points, and the third as its end 
point. 


The last curve in the sequence is per- 
mitted to have fewer than four points. 
If the curve has only one point, it is 
considered a point. If it has two 
points, it is a line segment. If it has 
three points, it is a parabola defined 
by drawing a Bezier curve with the 
first and third points as end points and 
the two control points equal to the sec- 


ond point. 
PM_POLYLINE- The points specify a list of coordinate 
SEGMENT (3) pairs. Line segments are drawn con- 


necting each successive pair of points. 
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Return Value 


Comments 


SET_SCREEN_ANGLE 


The return value is the previous poly mode. If the return value is zero, the device driver 
did not handle the request. 


An application should issue the SET_POLY_MODE escape before it draws a complex 
curve. It should then call the Polyline or Polygon function with the desired control points 
defining the curve. After drawing the curve, the application should reset the driver to its 
previous state by issuing the SET_POLY MODE escape. 


Polyline calls draw using the currently selected pen. 


Polygon calls draw using the currently selected pen and brush. If the start and end points 
are not equal, a line is drawn from the start point to the end point before filling the polygon 
(or curve). 


GDI treats Polygon calls using PM_POLYLINESEGMENT mode exactly the same as 
Polyline calls. 


Four points define a Bezier curve. GDI generates the curve by connecting the first and sec- 
ond, second and third, and third and fourth points. GDI then connects the midpoints of 
these consecutive line segments. Finally, GDI connects the midpoints of the lines connect- 
ing the midpoints, and so forth. 


The line segments drawn in this way converge to a curve defined by the following para- 
metric equations, expressed as a function of the independent variable ¢. 


X(t) = (1-1)x1 + 31-1)? tx2 + 3(1-1)172x3 + Pxa 


Y(t) = (1-#)°y1 + 3(1-1)ty2 + 3(1-y3 + Pya 


The points (x1,y1), (x2,y2), (x3,y3) and (x4,y4) are the control points defining the curve. 
The independent variable t varies from 0 to 1. 


Primitive types other than PM_BEZIER and PM_POLYLINESEGMENT may be added to 
this escape in the future. Applications should check the return value from this escape to de- 
termine whether or not the driver supports the specified poly mode. 


SET_SCREEN_ANGLE 


Syntax 


short Escape(i4DC, SET_SCREEN_ANGLE, sizeof(int), pAngle, NULL) 


This escape sets the current screen angle to the desired angle and enables an application to 
simulate the tilting of a photographic mask in producing a color separation for a particular 


primary. 
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Parameter Type/Description 

hDC HDC Identifies the device context. 

IpAngle LPINT Points to a short-integer value specifying the desired 
screen angle in tenths of a degree. The angle is measured coun- 
terclockwise. 

Return Value The return value is the previous screen angle. 
Commenis Four-color process separation is the process of separating the colors comprising an image 


into four component primaries: cyan, magenta, yellow, and black. The image is then repro- 
duced by overprinting each primary. 


In traditional four-color process printing, half-tone images for each of the four primaries 
are photographed against a mask tilted to a particular angle. Tilting the mask in this man- 
ner minimizes unwanted moire patterns caused by overprinting two or more colors. 


The device driver defines the default screen angle. 


SET_SPREAD 
Syntax short Escape(hDC, SET_SPREAD, sizeof(int), /pSpread, NULL) 


This function sets the amount that nonwhite primitives are expanded for a given device to 
provide a slight overlap between primitives to compensate for imperfections in the repro- 
duction process. 


Spot color separation is the process of separating an image into each distinct color used in 
the image. The image is reproduced by overprinting each successive color in the image. 


When reproducing a spot-separated image, the printing equipment must be calibrated to 
align each page exactly on each pass. However, differences in temperature, humidity, and 
so forth, between passes often cause images to align imperfectly on subsequent passes. For 
this reason, lines in spot separations are often widened (spread) slightly to make up for 
problems in registering subsequent passes through the printer. This process is called trap- 
ping. The SET_SPREAD escape implements this process. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpSpread LPINT Points to a short-integer value that specifies the 


amount, in pixels, by which all nonwhite primitives are to be ex- 
panded. . 
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STARTDOC 


Return Value 


The return value is the previous spread value. 


Comments The default spread is zero. 
The current spread applies to all bordered primitives (whether or not the border is visible) 
and text. 

STARTDOC 

Syntax short Escape(i4DC, STARTDOC, nCount, lpDocName, NULL) 


Return Value 


Commenis 


This escape informs the device driver that a new print job is starting and that all sub- 
sequent NEWFRAME escape calls should be spooled under the same job until an 
ENDDOC escape call occurs. This ensures that documents longer than one page will not 
be interspersed with other jobs. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
nCount short Specifies the number of characters in the string pointed 


to by the /pDocName parameter. 


IpDocName LPSTR Points to a null-terminated string that specifies the 
name of the document. The document name is displayed in the 
Print Manager window. The maximum length of this string is 31 
characters plus the terminating null character. 


The return value specifies the outcome of the escape. It is —1 if an error such as insufficient 
memory or an invalid port specification occurs. Otherwise, it is positive. 


The correct sequence of events in a printing operation is as follows: 


1. Create the device context. 


2. Set the abort function to keep out-of-disk-space errors from terminating a printing 
operation. 


An abort procedure that handles these errors must be set by using the SETABORT- 
PROC escape. 


3. Begin the printing operation with the STARTDOC escape. 


4, Begin each new page with the NEWFRAME escape, or each new band with the 
NEXTBAND escape. 
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5. End the printing operation with the ENDDOC escape. 

6. Destroy the cancel dialog box, if any. 

7. Free the procedure-instance address of the abort function. 

If an application encounters a printing error or a canceled print operation, it must not at- 
tempt to terminate the operation by using the Escape function with either the ENDDOC 


or ABORTDOC escape. GDI automatically terminates the operation before returning the 
error value. 


TRANSFORM_CTM 


Syntax 


Return Value 


Comments 


short Escape(hDC, TRANSFORM_CTM, 36, /pMatrix, NULL) 


This escape modifies the current transformation matrix. The current transformation matrix 
controls the manner in which coordinates are translated, rotated, and scaled by the device. 
By using matrices, you can combine these operations in any order to produce the desired 
mapping for a particular picture. 


The new current transformation matrix will contain the product of the matrix referenced by 
the /pMatrix parameter and the previous current transformation matrix (CTM = M x CTM). 


Parameter Type/Description 
hDC HDC Identifies the device context. 
[pMatrix LPSTR Points to a 3-by-3 array of 32-bit integer values speci- 


fying the new transformation matrix. Entries in the matrix are 
scaled to represent fixed-point real numbers. Each matrix entry 
is scaled by 65,536. The high-order word of the entry contains 
the whole integer portion, and the low-order word contains the 
fractional portion. 


The return value is TRUE if the escape was successful and FALSE if it was unsuccessful. 


Applications should not make any assumptions about the initial value of the current trans- 
formation matrix. 


The matrix specification used for this escape is based on the Microsoft OS/2 Presentation 
Manager graphics programming interface (GPI) model, which is an integer-coordinate sys- 
tem similar to the one used by GDI. 


Chapter || Assembly-Language 
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Assembly-language Microsoft Windows applications are highly structured as- 
sembly-language programs that use high-level-language calling conventions as 
well as Windows functions, data types, and programming conventions. Although 
you create assembly-language Windows programs by using the Microsoft Macro 
Assembler, the goal is to generate object files that are similar to the object files 
generated by the C Compiler. This chapter gives some guidelines that can help 
you meet this goal when creating assembly-language Windows applications. 


The SDK includes the file CMACROS.INC. This file contains high-level-lan- 
guage macros that define segments, programming models, function interfaces, 
and data types needed to create Windows applications. The Cmacros provide as- 
sembly-time options that define the memory model and the calling conventions 
that the application will use. The options must be selected in the assembly-lan- 
guage source file prior to the INCLUDE directive. 


This chapter provides an overview of the Cmacros and supplies important infor- 
mation on creating an assembly-language Windows application. The chapter 
covers the following topics: 

= How to create an assembly-language Windows application 


= Anoverview of the Cmacros 


= How to use the Cmacros in an assembly-language application 


13.1 Guidelines for Creating Assembly-Language Windows 
Applications 


When creating an assembly-language Windows application using the Cmacros, 
you should add the following to your application’s assembly-language source 
file: 


1. Specify the memory model by setting one of the options memS, memM, 
memC, or memL to 1. 


2. Specify the Pascal calling convention by setting the 7PLM option to 1. 


This is required for functions that will be called by Windows. 
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. Enable the Windows prolog and epilog by setting the ?WIN option to 1. 


This is required for callback functions or for exported functions in Windows 
libraries. 


. Include the CMACROS.INC file in the application source file. 


The statement that includes the CMACROS.INC file must come after the 
statements described in the preceding steps. 


. Create the application entry point, WinMain, and make sure that it is declared 


a public function. 


. Declare any callback functions as described in Section 13.1.6, “Declaring 


Callback Functions.” 


. After assembling the application source files, link your application’s as- 


sembled object files with the appropriate C-language library for Windows 
and C run-time libraries. 


The rest of this section describes these steps in more detail. 


13.1.1 Specifying a Memory Model 


The Cmacro memory-model options specify the memory model that the applica- 
tion will use. The memory model defines how many code and data segments are 
in the application. The following is a list of the possible memory models: 


Model Description 

Small One code segment and one data segment. 

Medium Multiple code segments and one data segment. 
Compact One code segment and multiple data segments. 
Large Multiple code and data segments. 

Huge Multiple code segments and multiple data segments 


with one or more data items larger than 64K. 


Select a memory model by defining the option name at the beginning of the as- 
sembly-language source file. Table 13.1 shows the option names available: 
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Table 13.1 Memory Options 


Option Memory Code Data 
Name Model Size Size 

memsS small small small 
memM medium large small 
memC compact small large 
memL large large large 
memH huge large large 


You can define a name by using the EQU directive. The definition has the fol- 
lowing form: 


memM EQU i 
If no option is selected, the default model is small. 


When you select a memory-model option, two symbols are defined. These two 
symbols can be used for code that is dependent on the memory model: 


SizeC 0 =small code 
1 = large code 

SizeD 0 =small data 
1 = large data 
2 = huge data 


13.1.2 Selecting a Calling Convention 


The Cmacro calling-convention option specifies the high-level-language calling 
convention that the application will use. You can select the calling convention by 
defining the value of the symbol ?PLM. Table 13.2 lists the values and conven- 
tions. 


Table 13.2 Calling Conventions 


2?PLM value Convention Description 


0 Standard C The caller pushes the rightmost argument onto the 
stack first, the leftmost last. The caller pops the ar- 
guments off the stack after control is returned. 


1 Pascal The caller pushes the leftmost argument onto the 
stack first, the rightmost last. The called function 
pops the arguments off the stack. 
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You can set the ?PLM symbol value by using the = directive. The statement has 
the following form: 


PLM = 1 


The default is the Pascal calling convention. The Pascal calling convention is re- 
quired for functions that are called by Windows. 


13.1.3 Enabling the Windows Prolog/Epilog Option 


The Windows prolog/epilog option is required for Windows applications. It speci- 
fies whether to use special prolog and epilog code with each function; this code 
defines the current data segment for the given function. 


You set this option by defining the value of the symbol ?WIN. Table 13.3 lists 
the values: 


Table 13.3. Prolog/Epilog Code Options 
?WIN value Meaning 


0 Disables the special prolog/epilog code. - 
Enables the special prolog/epilog code. 


You can set the ?WIN symbol value by using the = directive. The statement has 
the following form: 


?WIN = 1 


By default, the prolog and epilog code are enabled. 


13.1.4 Including the File CMACROS.INC 


The file CMACROS.INC contains the assembly-language definitions for all the 
Cmacro macros. You must include this file at the beginning of the assembly-lan- 


guage source file by using the INCLUDE directive. The line has the following 
form: 


INCLUDE CMACROS. INC 


You must give the full pathname if the macro file is not in the current directory 
or in a directory specified on the command line. 


For a complete description of each of the Cmacro macros, see Chapter 14, “As- 
sembly-Language Macros Directory.” 
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13.1.5 Creating the Application Entry Point 


Create the application entry point, WinMain, and make sure that it is declared a 
public function. It should have the following form: 


cProc WinMain, <PUBLIC>, <si,di> 
parmW hInstance 
parmW hPrevInstance 
parmD 1pCmdLine 
parmW nCmdShow 
cBegin WinMain 


cEnd WinMain 
sEnd 


The WinMain function should be defined within the standard code segment 
CODE. 


13.1.6 Declaring Callback Functions 


Make sure any callback functions are declared as follows: 


cProc TestWndProc, <FAR,PUBLIC>, <si,di> 
parmW hWnd 
parmW message 
parmW wParam 
parmD 1Param 
cBegin TestWndProc 


cEnd TestWndProc 


Callback functions must be defined within a code segment. 


13.1.7 Linking with Libraries 


After assembling your application’s source files, you should link the assembled 
object files with the appropriate C-language libraries. 


If the entire application is written in assembly language, to link properly you may 
need to add an external definition for the absolute symbol __acrtused in your 
application source file. 
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13.1.8 Enabling Stack Checking 


You can enable stack checking by defining the symbol ?CHKSTK. When stack 
checking is enabled, the prolog code calls the externally defined routine 
CHKSTK to allocate local variables. 


You can define the ?CHKSTK symbol by using the = directive. The statement 
has the following form: 


?CHKSTK = 1 
Once CHKSTK is defined, stack checking is enabled for the entire file. 
The default (when CHKSTK is not defined) is no stack checking. 


13.2 Cmacro Groups 


Chapter 14, “Assembly-Language Macros Directory,” lists and describes the 
Cmacro macros, a set of assembly-language macros that can be used with the 
Microsoft Macro Assembler (MASM) to create assembly-language Windows 
applications. The Cmacros provide a simplified interface to the function and seg- 
ment conventions of high-level languages such as C. 


The Cmacros are divided into the following groups: 


= Segment macros 

= Storage-allocation macros 
= Function macros 

= Call macros 

m@ Special-definition macros 


m Error macros 


The rest of this section briefly describes each group of macros. 


13.2.1 Segment Macros 


Segment macros give access to the code and data segments that an application 
will use. These segments have the names, attributes, classes, and groups required 
by Windows. 


The Cmacros have two predefined segments, named CODE and DATA, that any 
application can use without special definition. 
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Macro Name 


createSeg 
sBegin 
sEnd 


assumes 


dataOFFSET 


codeOFFSET 


segNameOFFSET 


13.2.2 Storage-Allocation Macros 


Description 


Creates a new segment that has the specified name 
and segment attributes. 


Opens up a segment (this macro is similar to the 
SEGMENT assembler directive). 


Closes a segment (this macro is similar to the ENDS 
assembler directive). 


Makes all references to data and code in the segment 
segName relative to the segment register given by 
segReg. It is similar to the ASSUME assembler 
directive. 


Generates an offset relative to the start of the group 
to which the DATA segment belongs. It is similar to 
the OFFSET assembler operator, but automatically 
provides the group name. 


Generates an offset relative to the start of the group 
to which the CODE segment belongs. It is similar to 
the OFFSET assembler operator, but automatically 
provides the group name. 


Generates an offset relative to the start of the group 
to which the user-defined segment segName 

belongs. It is similar to the OFFSET assembler oper- 
ator, but automatically provides the group name. 


Storage-allocation macros allocate static memory (either private or public), de- 
clare externally defined memory and procedures, and allow the definition of 


public labels. 


Macro Name 
staticX 
globalX 
externX 


labelX 


Description 
Allocates private static-memory storage. 
Allocates public static-memory storage. 


Defines one or more names that will be the labels of 
external variables or functions. 


Defines one or more names that will be the labels of 
public (global) variables or functions. 
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13.2.3 Function Macros 


Function macros define the names, attributes, parameters, and local variables of 


functions. 


Macro Name 


cProc 
parmX 
localX 
cBegin 
cEnd 


13.2.4 Call Macros 


Description 
Defines the name and attributes of a function. 


Defines one or more function parameters. The para- 
meters provide access to the arguments passed to the 
function. 


Defines one or more frame variables for the 
specified function. 


Defines the actual entry point for the specified func- 
tion. 


Defines the exit point for the specified function. 


Call macros can be used to call cProc functions and high-level-language func- 
tions. These macros pass arguments according to the calling convention defined 


by the ?PLM option. 


Macro Name 


cCall 


Save 


Arg 


13.2.5 Special-Definition Macros 


Description 


Pushes the specified arguments onto the stack, saves 
registers (if any), and calls the specified function. 


Directs the next cCall macro to save the specified 
registers on the stack before calling a function, and 
to restore the registers after the function returns. 


This macro defines the arguments to be passed to a 
function by the next cCall macro. 


Special-definition macros inform the Cmacros about user-defined variables, func- 
tion-register use, and register pointers. 
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Macro Name Description 

Def Registers the name of a user-defined variable with 
the Cmacros. 

FarPtr Defines a 32-bit pointer value that can be passed as 


a single argument in a cCall macro. 


13.2.6 Error Macros 


Error macros generate an error message to the console and an error message in 
the listing. Both the text that caused the error and the result of its evaluation are 
displayed in the generated error message. 


Error macros let you code assertions into an assembly-language source program. 
This lets you code optimum instruction sequences for some operations based on 
the variable allocation or bit position of flag in a word, and assert that the as- 
sumptions made are true. 


Macro Name Description 


errnz Evaluates a given expression. If the result is not 
zero, an error is displayed. 


errn$ Subtracts the offset of the /abe! parameter from the 
offset of the location counter, then adds the bias 
parameter to the result. If this result is not zero, then 
an error message is displayed. 


13.3 Using the Cmacros 


This section explains the assembly-language statements generated by some of the 
Cmacros and illustrates their use with an example of a Cmacros function called 
BITBLT. 


13.3.1 Overriding Types 


Parameters and local variables created using the parmX and localX macros actu- 
ally correspond to expressions of the following form: 


localB x == x equ byte ptr [bp+nn] 
parmB y = y equ byte ptr [bp+nn] 


In this example, the nn parameter specifies an offset from the current bp register 
value. 
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These expressions let you use the names without having to explicitly type in 
“type ptr” and “[bpt+offset]” operators. This means that “x” can be referred to as 
follows: 


mov al,x 
and that “‘y” can be referred to as follows: 
mov ax,y 


A problem arises if the type must be overridden. The assembler creates an error 
message if it encounters the following line: 


mov ax,word ptr x 


This can be solved by enclosing the name in parentheses: 
mov ax,word ptr (x) 


One exception to this pattern is the localV macro. The expression generated by 
this macro does not have a type associated with it. Therefore it can be overridden 
without the parentheses. For example: 


local¥ horse,1@ ==> horse equ [bp+nn] 


13.3.2 Symbol Redefinition 


Any symbol defined by a parmX macro in one function can be redefined as a 
parameter in any other function. This allows different functions to refer to the 
same parameter by the same name, regardless of its location on the stack. 


13.3.3 Cmacros: a Sample Function 


The following example defines the assembly function BITBLT, which is a FAR 
and PUBLIC type function. When BITBLT is invoked, the SI and DI registers 
are automatically saved, and automatically restored upon exit. The BP register is 
always saved. 


BITBLT is passed seven double-word pointers on the stack. Space will be allo- 
cated on the stack for eight frame variables (one structure, five bytes, and two 
words). 


The cBegin macro defines the start of the actual code. The pExt parameter is 
loaded, and some values are loaded into registers. The AX and BX registers are 
saved on the following cCall. 


Another C function, There, is invoked by the cCall macro. Four arguments are 
passed to There: pDestBitmap, the 32-bit pointer in DS:SI, register AX, and 
register BX. The cCall macro places the arguments on the stack in the correct 
order. 
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When There returns, the arguments placed on the stack are automatically 
removed, and the AX and BX registers are restored. 


When cEnd is reached, the frame variables are removed, any autosave registers 
are restored, and a return of the correct type (near or far) is performed. 


The following example shows how the BITBLT function is defined: 


cProc BITBLT,<FAR,PUBLIC>,<si,di> 


parmD 
parmD 
parmD 
parmD 
parmD 
parmD 
parmD 


localV 


localB 
localB 
localB 


localW 
localW 


localB 
localB 


cBegin 
lds 
mov 


mov 


RegPtr 
Save 


cCal] 


pDestBitmap 3—> to dest bitmap descriptor 
pDestOrg 3—> to dest origin (a point) 
pSrcBitmap 3—> to source bitmap descriptor 
pSrcOrg 3—> to source origin 

pExt ;-> to rectangle extent 

pRop 3—-> to rasterop descriptor 
pBrush ;-> to a physical brush 

nOps,4 ;# of each operand used 

phaseH ;sHorizontal phase (rotate count) 
PatRow ;Current row for patterns [@..7] 
direction ;Increment/decrement flag 
startMask smask for first dest byte 
lastMask ;mask for last dest byte 
firstFetch s;Number of first fetches needed 
stepDirection ;Direction of move (left, right) 
$1, PEXt 


ax,extentXx[si] 
bx,extentY[si] 


dest,ds,si 
<ax ,Dx> 


THERE, <pDestBitmap,dest,ax,bx> 


extentX[si],cx 
extentY[si],dx 
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13.4 Summary 


The CMACROS.INC file defines segments, programming models, function 
interfaces, and data types needed to create Windows applications. The Cmacros 
provide assembly-time options that define the memory model and the calling con- 
ventions that the application will use. For more information on topics related to 
the Cmacros, see the following: 


Topic Reference 

Cmacro descriptions Reference, Volume 2: Chapter 14, 
“Assembly-Language Macros Directory” 

Using the linker Tools: Chapter 2, “Linking Applications: The 
Linker” 

Using the Macro Assembler Microsoft Macro Assembler Programmer's 


Guide 


Chapter 


14 


Assembly-Language 
Macros Directory 


This chapter describes the Cmacros, a set of assembly-language macros that 
can be used with the Microsoft Macro Assembler (MASM) to create assembly- 
language Windows applications. The Cmacros provide a simplified interface to 
the function and segment conventions of high-level languages such as C. 


This section lists the Cmacros in alphabetical order, and describes each macro in 
detail. 
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Arg 

Syntax Arg namelist 
This macro defines the arguments to be passed to a function by the next cCall macro. The 
arguments are pushed onto the stack in the order given. This order must correspond to the 
order of the function parameters. 
More than one Arg macro can be given before each cCall. Multiple Arg macros have the 
same effect as a single macro. 
The namelist parameter specifies a list of argument names to be passed to the function. All 
names must have been previously defined. 

Comments Byte-type parameters are passed as words. There is no sign extension or zeroing of the 
high-order byte. 
Immediate arguments are not supported. 

Examples Arg varl 
Arg var2 
Arg var3 
Arg <varl,var2,var3> 

assumes 

Syntax assumes segReg, segName 
This macro makes all references to data and code in the segment segName relative to the 
segment register given by segReg. It is similar to the ASSUME assembler directive. 
The segReg parameter specifies the name of a segment register. 
The segName parameter specifies the name of a predefined segment, CODE or DATA, or 
a user-defined segment. 

Examples assumes CS, CODE 
assumes DS, CODE 

cBegin 

Syntax cBegin [[procName] 


This macro defines the actual entry point for the function procName. The macro creates 
code that sets up the frame and saves registers. 
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cCall 


SE SN a DE TT Pg TO 


The optional procName parameter specifies a function name. If it is given, it must be the 
same as the name given in the cProc macro immediately preceding the cBegin macro. 


cCall 
Syntax 


Comments 


Examples 


cCall procName, [<argList>], [|<underscores>]| 


This macro pushes the arguments in argList onto the stack, saves registers (if any), and 
calls the function procName. 


The procName parameter specifies the name of the function to be called. 


The optional argList parameter specifies a list of the names of arguments to be passed to 
the function. This list is not required if the Arg macro is used before cCall. 


The optional underscores parameter specifies whether an underscore should be added to 
the beginning of procName. If this argument is blank and the calling convention is the C 
calling convention, an underscore is added. 


The arguments of an Arg macro are pushed onto the stack before any arguments in the ar- 
gList parameter of a cCall macro. 


Byte-type parameters are passed as words. There is no sign extension or zeroing of the 
high-order byte. 


Immediate arguments are not supported. 


cCall there, <pExt,ax,bx,pResul t> 


Arg pExt 
Arg ax 
cCall there,<bx,pResult> 


cEnd 
Syntax 


cEnd [[procName] 


This macro defines the exit point for the procName function. The macro creates code that 
discards the frame, restores registers, and returns to the caller. 


The optional procName parameter specifies a function name. If it is given, it must be the 
same as the name given in the cBegin macro immediately preceding the cEnd macro. 


Once a function has been defined using cProc, any formal parameters should be declared 
with the parmX macro and any local variables with the localX macro. The cBegin and 
cEnd macros must be used to delineate the code for the function. 
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The following is an example of a complete function definition: 


Example cProc strcpy,<PUBLIC>,<si,di> 
parmW dst 
parmW src 
localW cnt 


cBegin 
cld 
mov $1,ShC 
mov di,dest 
push ds 
pop es 
xor CX CX 
mov enit;.cx 
loop: 
lodsb 
stosb 
inc cnt 
cmp al ,@ 
jnz loop 
mov ax,cnt 
cEnd 
codeOFFSET 
Syntax codeOFFSET arg 
This macro generates an offset relative to the start of the group to which the CODE seg- 
ment belongs. It is similar to the OFFSET assembler operator, but automatically provides 
the group name. For this reason, it should be used instead of OFFSET. 
The arg parameter specifies a label name or offset value. 
Example mov ax,codeOFFSET label 


-—_ooeo eee 


cProc 

Syntax cProc procName, <attributes>, <autoSave> 
This macro defines the name and attributes of a function. 
The procName parameter specifies the name of the function. 


The attributes parameter specifies the function type. It can be a combination of the follow- 
ing: 
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createSeg 


Comments 


Examples 


Type Description 


NEAR A near function. It can only be called from the segment in 
which it is defined. 


FAR A far function. It can be called from any segment. 
PUBLIC A public function. It can be externally declared in other 


source files. 


The default attribute is NEAR and private (i.e., cannot be declared externally in other 
source files). The NEAR and FAR attributes cannot be used together. If more than one at- 
tribute is selected, the angle brackets are required. 


The autoSave parameter specifies a list of registers to be saved when the function is in- 
voked, and restored when exited. Any of the 8086’s registers can be specified. 


If this function is called by a function written in C, it must save and restore the SI and DI 
registers. 


The BP register is always saved, regardless of whether it is present in the autoSave list. 
cProc procl, <FAR, ds,es> 


cProc proc2, <NEAR,PUBLIC> 
cProc proc3,,ds 


createSeg 
Syntax 


createSeg segName, logName, align, combine, class 


This macro creates a new segment that has the specified name and segment attributes. The 
macro automatically creates an assumes macro and an OFFSET macro for the new seg- 
ment. This macro is intended to be used in medium-model Windows applications to define 
nonresident segments. The segName parameter specifies the actual name of the segment. 
This name is passed to the linker. 


The JogName parameter specifies the logical name of the segment. This name is used in all 
subsequent sBegin, sEnd, and assumes macros that refer to the segment. 


The align parameter specifies the alignment type. It can be any one of the following: 


BYTE 
WORD 
PARA 
PAGE 
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Example 


Comments 


dataOFFSET 
Syntax 


Example 


The combine parameter specifies the combine type for the segment. It can be any one of 
the following: 


COMMON 
MEMORY 
PUBLIC 
STACK 


If no combine type is given, a private segment is assumed. 


The class parameter specifies the class name of the segment. The class name defines 
which segments must be loaded in consecutive memory. 


createSeg _INIT,INITCODE,BYTE,PUBLIC,CODE 


sBegin INITCODE 
assumes CS: INITCODE 


mov ax,initcodeOFFSET sample 


sEnd INITCODE 


The alignment, combine type, and class name are described in detail in the Microsoft 
Macro Assembler Reference . 


The Cmacros have two predefined segments, named CODE and DATA, that any applica- 
tion can use without special definition. Medium-, large-, and huge-model applications can 
define additional segments by using the createSeg macro. 


dataOFFSET arg 


This macro generates an offset relative to the start of the group to which the DATA seg- 
ment belongs. It is similar to the OFFSET assembler operator, but automatically provides 
the group name. For this reason, it should be used instead of OFFSET. 


The arg parameter specifies a label name or offset value. 


mv ax,dataQFFSET label 
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DefX 
Syntax - DefX <namelist> 
This macro registers the name of a user-defined variable with the Cmacros. Variables that 
are not defined using the staticX, globalX, externX, parmX, or localX macros cannot be 
referred to in other macros unless the name is registered, or the variable was defined with 
the DW assembler directive. 
The X parameter specifies the storage size of the variable. It can be any one of the follow- 
ing: 
Type Description 
B Byte 
Ww Word 
D Double-word 
Q Quad-word 
T Ten-byte word 
CP Code pointer (one word for small and compact models) 
DP Data pointer (one word for small and medium models) 
The namelist parameter specifies a list of variable names to be defined. 
Example maxSize db 132 
DefB maxSize 
dest equ. wordptr es:[di] 
DefW dest 
errn$ 
Syntax errn$ label, [bias] 


This macro subtracts the offset of /abel from the offset of the location counter, then adds 
bias to the result. If this result is not zero, then an error message is displayed. 


The /abel parameter specifies a label corresponding to a memory location. 


The optional bias parameter specifies a signed bias value. A plus or minus sign is required. 


errnz 
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Example 


: end of previous code 
errn$ functionl 
functionl: 


If a function that was originally located immediately after another piece of code is ever 
moved, errn$ displays an error message. 


errnz 
Syntax 


Examples 


errnz <expression> 
This macro evaluates a given expression. If the result is not zero, an error is displayed. 
The expression parameter specifies the expression to be evaluated. The angle brackets are 
required if there are any spaces in the expression. 
x db ? 

db ? 


mov ax, word ptr x 
errnz <COFPSET y) = COPFSED x) --1> 


If during assembly, x and y receive anything but sequential storage locations, errnz dis- 
plays an error message. 


tablel struc 


tablellen equ $-tablel 
tablel ends 


table2 struc 


table2len equ $-table2 
table2 ends 


errnz tablelLen-table2Len 


If during assembly, the length of two tables is not the same, errnz displays an error 
message. 
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externX 
Syntax externX <namelist> 
This macro defines one or more names that will be the labels of external variables or func- 
tions. 
The X parameter specifies the storage size or function type. It can be any one of the follow- 
ing: 
Type Description 
A Constant value declared with the EQU and = directives in a 
separate file 
B Byte 
Ww Word 
D Double-word 
Q Quad-word 
T Ten bytes 
CP Code pointer (one word for small and compact models) 
DP Data pointer (one word for small and medium models) 
NP Near function pointer 
FP Far function pointer 
Pp Near for small and compact models; far for other models 
The namelist parameter specifies the list of the names of the variables or functions. 
Examples externB <DataBase> 
externFP <SampleRead> 
FarPtr 
Syntax FarPtr name, segment, offset 


This macro defines a 32-bit pointer value that can be passed as a single argument in a 
cCall macro. In the FarPtr macro, the segment and offset values do not have to be in 
registers. 


The name parameter specifies the name of the pointer to be created. 
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The segment parameter specifies the text that defines the segment portion of the pointer. 


The offset parameter specifies the text that defines the offset portion of the pointer. 


Example FarPtr destPtr,es,<wordptr 3[si]> 
cCall proc,<destPtr,ax> 


globalX 
Syntax globalX name, [initialValue] [Lreplication] 
This macro allocates public static-memory storage. 
The X parameter specifies the size of the storage to be allocated. It can be any one of the 
following: 
Type Description 
B Byte 
Ww Word 
D Double-word 
Q Quad-word 
T Ten bytes 
CP Code pointer (one word for small and compact models) 
DP Data pointer (one word for small and medium models) 
The name parameter specifies the reference name of the allocated memory. 
The optional initialValue parameter specifies an initial value for the storage. The default is 
zero if no value is specified. 
The optional replication parameter specifies a count of the number of times the allocation 
is to be duplicated. This parameter generates the DUP assembler operator. 
Examples globalW flag,l 


globalB string,@, 30 
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labelX 
Syntax labelX <namelist> 
This macro defines one or more names that will be the labels of public (global) variables 
or functions. 
The X parameter specifies the storage size or function type. It can be any one of the follow- 
ing: 
Type Description 
B Byte 
Ww Word 
D Double-word 
Q Quad-word 
T Ten bytes 
CP Code pointer (one word for small and compact models) 
DP Data pointer (one word for small and medium models) 
NP Near function pointer 
FP Far function pointer 
P Near for small and compact models; far for other models 
The namelist parameter specifies the list of the names of the external variables or func- 
tions. 
Examples labelB <DataBase> 
labelFP <SampleRead> 
localX 
Syntax localX <namelist>, size 


This macro defines one or more frame variables for the function. To keep the words in the 
stack aligned, the macro ensures that the total space allocated is an even number of bytes. 
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The X parameter specifies the storage size. It can be any one of the following: 


Type Description 

B Byte (allocates a single byte of storage on the stack) 
Ww Word (allocated on a word boundary) 

D Double-word (allocated on a word boundary) 

Vv Variable size (allocated on a word boundary) 

Q Quad-word (aligned on a word boundary) 

T Ten-byte word (aligned on a word boundary) 

CP Code pointer (one word for small and compact models) 
DP Data pointer (one word for small and medium models) 


The namelist parameter specifies the list of the names of the frame variables for the func- 
tion. 


The size parameter specifies the size of the variable. It is used with localV only. 


Commenis B-type variables are not necessarily aligned on word boundaries. 


The localD macro creates two additional symbols, OFF_name and SEG_name. 
OFF _name is the offset portion of the parameter; SEG_name is the segment portion. 


Only the name is required when referencing a variable. Write your code like this: 
mov al,varl 
Not like this: 


mov al,byte ptr varl{bp] 


Examples localB <L1,L2,L3> 
localW L4 
localD <L5> 
localV L6,%(size struc) 
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parmxX 
Syntax parmX <namelist> 
This macro defines one or more function parameters. The parameters provide access to the 
arguments passed to the function. Parameters must appear in the same order as the argu- 
ments in the function call. 
The X parameter specifies the storage size. It can be any one of the following: 
Type Description 
B Byte (allocated on a word boundary on the stack) 
Ww Word (allocated on a word boundary) 
D Double-word (allocated on a word boundary) 
Q Quad-word (aligned on a word boundary) 
T Ten-byte word (aligned on a word boundary) 
CP Code pointer (one word for small and compact models) 
DP Data pointer (one word for small and medium models) 
The namelist parameter specifies the list of the parameter names. 
Comments The parmD macro creates two additional symbols, OFF_name and SEG_name. 
OFF _name is the offset portion of the parameter; SEG_name is the segment portion. 
Only the parameter name is required when referring to the corresponding argument. Write 
your code like this: 
mov al,varl 
Not like this: 
mov al,byte ptr varl[bp] 
Examples parmW varl 


parmB <var2,var3,var4> 
parmD <var5> 


Save 
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Save 
Syntax Save <regList> 
This macro directs the next cCall macro to save the specified registers on the stack before 
calling a function, and to restore the registers after the function returns. The macro can be 
used to save registers that are destroyed by the called function. 
The Save macro applies to only one cCall macro; each new cCall must have a correspond- 
ing Save macro. If two Save macros appear before a cCall, only the second macro is recog- 
nized. 
The regList parameter specifies a list of registers to be saved. 
Examples Save <cl,bh,si> 
Save <ax> 
sBegin 
Syntax sBegin segName 
This macro opens up a segment. It is similar to the SEGMENT assembler directive. 
The segName parameter specifies the name of the segment to be opened. It can be one of 
the predefined segments, CODE or DATA, or the name of a user-defined segment. 
Examples sBegin DATA 
sBegin CODE 
segNameOFFSET 
Syntax segNameOFFSET arg 


Example 


This macro generates an offset relative to the start of the group to which the user-defined 
segment segName belongs. It is similar to the OFFSET assembler operator, but automati- 
cally provides the group name. For this reason, it should be used instead of OFFSET. 


The arg parameter specifies a label name or offset value. 


mv ax,initcodeOFFSET label 
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sEnd 


sEnd 
Syntax 


Examples 


staticX 
Syntax 


Examples 


sEnd [[segName]| 
This macro closes a segment. It is similar to the ENDS assembler directive. 


The optional segName parameter specifies a name used for readability. If it is given, it 
must be the same as the name given in the matching sBegin macro. 


sEnd 
sEnd DATA 


staticX name, [initialValue], [replication] 
This macro allocates private static-memory storage. 


The X parameter specifies the size of storage to be allocated. It can be any one of the fol- 
lowing: 


Type Description 

B Byte 

Ww Word 

D Double-word 

Q Quad-word 

T Ten bytes 

CP Code pointer (one word for small and compact models) 
DP Data pointer (one word for small and medium models) 


The name parameter specifies the reference name of the allocated memory. The optional in- 
itialValue parameter specifies an initial value for the storage. If no value is specified, the 
default is zero. 


The optional replication parameter specifies a count of the number of times the allocation 
is to be duplicated. This parameter generates the DUP assembler operator. 


staticW flag,l 
staticB string, , 30 
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The Microsoft Windows Dynamic Data Exchange (DDE) protocol defines the 
method for communicating among applications. This communication takes place 
as applications send messages to each other to initiate conversations, to request 
and share data, and to terminate conversations. This chapter describes these mes- 
sages and the rules associated with their use. It also briefly describes several clip- 
board formats which a DDE application can register for use ina DDE 
conversation. 


Guide to Programming provides an overview of DDE programming, including 
such concepts as client, server, application, topic and item. It also introduces the 
modes of DDE communication, including permanent data links, one-time trans- 
fers, and remote command execution, and it explains the flow of DDE messages. 


Conventions Used in This Chapter 


Message-specific argument names bear prefixes indicating their type, as follows: 


Prefix Description 

a An atom of word length (16 bits); for example, aName. 

ct: A registered clipboard format number (word length); for 
example, cfFormat. 

f A flag bit; for example, fName. 

h A handle (word length) to a global memory object; for 


example, hName. 


w Any other word-length argument; for example, wName. 


15.1 Using the DDE Message Set 


Each DDE message has two parameters. The first parameter, wParam (word 
length), carries the handle of the sender’s window; it is the same in all cases and 
so is not shown in Table 15.1. The second parameter, /Param (a long word, 32 
bits), is composed of a low-order word and a high-order word containing 
message-specific arguments, as follows: 
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Table 15.1 DDE Messages 


Arguments in /Param 


Message Low-order word High-order word 
WM_DDE_ACK 

In reply to INITIATE aApplication aTopic 

In reply to EXECUTE wStatus hCommands 

All other messages wStatus altem 
WM_DDE_ADVISE hOptions altem 
WM_DDE_DATA hData altem 
WM_DDE_EXECUTE (Reserved) hCommands 
WML_DDE_INITIATE aApplication aTopic 
WM_DDE_POKE hData altem 
WM_DDE_REQUEST cfFormat altem 
WM_DDE_TERMINATE (Reserved) (Reserved) 
WM_DDE_UNADVISE (Reserved) altem 


An application calls the SendMessage function to issue the WM_DDE_INIT- 
IATE message or a WM_DDE_ACK message sent in response to 
WM_DDE_INITIATE. All other messages are sent using the PostMessage 
function. The window handle of the receiving window appears as the first para- 
meter of these calls. The second parameter contains the message to be sent, the 
third parameter identifies the sending window, and the fourth parameter contains 
the message-specific arguments. For example: 


PostMessage(hwndRecipient, WM_DDE_MESSAGE, hwndSender, 
MAKELONG(1low_word, high_word) ) 


The MAKELONG macro combines low_word and high_word into a long word. 


15.2 Synchronizing the DDE Conversation 


An application window that processes DDE requests from the window of a DDE 
partner must process them strictly in the order in which they are received from 
that partner. However, when handling messages from multiple DDE partners, the 
window does not have to follow this “first in, first out” rule. In other words, only 
the conversations themselves must be synchronous; the window can shift from 
one conversation to another asynchronously. 


For example, suppose the following messages are in a window’s queue: 
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Message from window X 
Message from window Y 
Message from window X 


The window must process message | before message 3, but it need not process 
message 2 before message 3. If window Y is a lower-priority DDE-conversation 
partner than window X, the window can defer processing the messages from 
window Y until it has finished dealing with the messages sent by window X. The 
following shows acceptable processing orders for these messages and the relative 
priority implied by each order: 


Order Relative Priority 


1 2 3  £4Window X = window Y 
1 3 2 Window X> window Y 


2 1 3 Window X < window Y 


If an application is unable to process an incoming request because it is waiting 
for a DDE response, it must posta WM_DDE_ACK message with the fBusy 
flag set to 1 to prevent deadlock. An application can also send a busy 
WM_DDE_ACK message if for any reason the application cannot process 

an incoming request within a reasonable amount of time. 


An application should be able to deal with the situation in which its DDE partner 
fails to respond with a message within a certain time-out interval. Since the 
length of this interval may vary depending on the nature of the application and 
the configuration of the user’s system (including whether it is on a network), the 
application should provide a way for the user to specify the time-out interval. 


15.3 Using Atoms 


Certain arguments of DDE messages (altem, aTopic, and aApplication) are 

global atoms. Applications using these atoms must explicitly delete them to 
purge them from the atom list. Section 15.7, “DDE Message Directory,” de- 
scribes the rules for allocating and deleting atoms used by each message. 


In all cases, the sender of a message must delete any atom which the intended 
receiver will not receive due to an error condition, such as failure of the Post- 
Message function. 
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15.4 Using Shared Memory Objects 
DDE uses shared memory objects for three purposes: 


= To carry a data item value to be exchanged. This is an item referenced by the 
hData argument in the WM_DDE_DATA and WM_DDE_POKE messages. 


= Tocarry options in a message. This is an item referenced by the AOptions ar- 
gument ina WM_DDE_ADVISE message. 


= To carry an execution-command string. This is an item referenced by the 
hCommands argument in the WM_DDE_EXECUTE message and its corre- 
sponding WM_DDE_ACK message. 


Applications that receive a DDE shared memory object must treat it as read only. 
It must not be used as a mutual read/write area for the free exchange of data. 


As with a DDE atom, a shared memory object should be freed properly to pro- 
vide for effective memory management. Shared memory objects should be prop- 
erly locked and unlocked. Section 15.7, “DDE Message Directory,” describes the 
rules for allocating and deleting shared memory objects used by each message. 


In all cases, the sender of a message must delete any shared memory object 
which the intended receiver will not receive due to an error condition, such as 
failure of the PostMessage function. 


15.5 Using Clipboard Formats 


You can pass data by means of any of the standard clipboard formats or with a 
registered clipboard formats. See the description of the SetClipboardData func- 
tion in Chapter 4, “Functions Directory,” in Reference, Volume 1, for more infor- 
mation on standard clipboards. See the description of the RegisterClipboard- 
Format function for information on registering clipboard formats. 


A special, registered format named Link is used to identify an item in a DDE 
conversation. For more information, see Guide to Programming. 


15.6 Using the System Topic 


Applications are encouraged to support at all times a special topic with the name 
System. This topic provides a context for items of information that may be of 
general interest to another application. 


The following list contains suggested items for the System topic. This list is not 
exclusive. The data item values should be rendered in the CF_TEXT format. 
Individual elements of a System topic item value should be delimited by tab 
characters. 
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Item Description 

SyslItems A list of the System-topic items supported by the appli- 
cation. 

Topics A list of the topics supported by the application at the 
current time; this list can vary from moment to mo- 
ment. 

ReturnMessage Supporting detail for the most recently used 


WM_DDE_ACK message. This is useful when more 
than eight bits of application-specific return data are 
required. 


Status An indication of the current status of the application. 
When a server receives a WM_DDE_REQUEST 
message for this System-topic item, it should respond 
by posting a WM_DDE_DATA message with a string 
containing either “Busy” or “Ready,” as appropriate. 


Formats A list of clipboard format numbers that the application 
can render. 


15.7 DDE Message Directory 


This section describes the nine DDE messages. Included in each description is a 
list of the message-specific arguments and the rules for posting and receiving 
each message. The SDK contains the DDE.H header file which defines the DDE 
messages and data structures described in this section. 
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WM_DDE_ACK 


This message notifies an application of the receipt and processing of a WM_DDE_IN- 
ITIATE, WM_DDE_EXECUTE, WM_DDE_DATA, WM_DDE_ADVISE, 
WM_DDE_UNADVISE, or WM_DDE_POKE message, and in some cases, of a 
WM_DDE_REQUEST message. 


Parameter Description 

wParam Identifies the sending window. 

[Param The meaning of the low-order and high-order words depends on 
the message to which the WM_DDE_ACK message is respond- 
ing. 


When responding to WM_DDE_INITIATE: 


Argument Description 

aApplication Low-order word of /Param. An atom that 
contains the name of the replying applica- 
tion. 

aTopic High-order word of /Param. An atom 


that contains the topic with which the re- 
plying server window is associated. 


When responding to WM_DDE_EXECUTE: 


Argument Description 

wStatus Low-order word of /Param. A series of 
flags that indicate the status of the re- 
sponse. 

hCommands High-order word of /Param. A handle 


that identifies the data item containing 
the command string. 
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Parameter Description 


When replying to all other messages: 


Argument Description 

wStatus Low-order word of /Param. A series of 
flags that indicate the status of the re- 
sponse. 

altem High-order word of /Param. An atom 


that specifies the data item for which the 
response is sent. 


Comments The wStatus word consists of a DDEACK data structure that contains the following infor- 
mation: 
Bit Name Meaning 
15 fAck 1 = Request accepted. 


0 = Request not accepted. 


14 fBusy 1 = Busy. An application is expected to set 
fBusy if it is unable to respond to the request at 
the time it is received. The fBusy flag is defined 
only when fAck is zero. 


0 = Not busy. 
13-8 Reserved for Microsoft use. 
7-0 bAppReturnCode Reserved for application-specific return codes. 
Posting Except in response to the WM_DDE_INITIATE message, post the WM_DDE_ACK 


message by calling the PostMessage function, not SendMessage. When responding to 
WM_DDE_INITIATE, send the WM_DDE_ACK message with SendMessage. 


When acknowledging any message with an accompanying a/tem atom, the application that 
sends WM_DDE_ACK can reuse the a/tem atom that accompanied the original message, 
or it may delete it and create a new one. 


When acknowledging WM_DDE_EXECUTE, the application that sends WM_DDE_ACK 
should reuse the hCommands object that accompanied the original WM_DDE_EXECUTE 
message. 
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If an application has initiated the termination of a conversation by sending 
WM_DDE_TERMINATE and is awaiting confirmation, the waiting application should not 
acknowledge (positively or negatively) any subsequent message sent by the other applica- 
tion. The waiting application should delete any atoms or shared memory objects received 
in these intervening messages. 


Receiving The application that receives WM_DDE_ACK should delete all atoms accompanying the 
message. 


If the application receives WM_DDE_ACK in response to a message with an accompany- 
ing hData object, the application should delete the hData object. 


If the application receives a negative WM_DDE_ACK message sent in reply to a 
WM_DDE_ADVISE message, the application should delete the hOptions object sent with 
the original WM_DDE_ADVISE message. 


If the application receives a negative WM_DDE_ACK message sent in reply to a 
WM_DDE_EXECUTE message, the application should delete the hCommands object sent 
with the original WM_DDE_EXECUTE message. 


WM_DDE_ADVISE 


This message, posted by a client application, requests the receiving (server) application to 
supply an update for a data item whenever it changes. 


Parameter Description 
wParam Identifies the sending window. 
lParam Identifies the requested data and specifies how the data is to be 
sent. 
Argument Description 
hOptions Low-order word of /Param. A handle to 
a global memory object that specifies 
how the data is to be sent. 
altem High-order word of /Param. An atom 
that specifies the data item being re- 
quested. 
Commenis The global memory object identified by hOptions consists of a DDEADVISE data struc- 


ture that contains the following: 
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Word Name Content 

1 fAckReq If bit 15 is 1, the receiving (server) application 
is requested to send its WM_DDE_DATA mes- 
sages with the ACK-requested bit (fAckReq) 
set. This offers a flow-control technique 
whereby the client application can avoid over- 
load from incoming DATA messages. 

fDeferUpd If bit 14 is 1, the server is requested to send its 
WM_DDE_DATA messages with a null hData 
handle. These messages are alarms telling the 
client that the source data has changed. Upon re- 
ceiving one of these alarms, the client can 
choose to call for the latest version of the data 
by issuing a WM_DDE_REQUEST message, 
or it can choose to ignore the alarm altogether. 
This would typically be used when there is a 
substantial resource cost associated with render- 
ing and/or assimilating the data. 

reserved Bits 13-0 are reserved. 

2 cfFormat The client’s preferred type of data. Must be a 
standard or registered clipboard data format 
number. 

If an application supports more than one clipboard format for a single topic and item, it 

can post multiple WM_DDE_ADVISE messages for the topic and item, specifying a differ- 

ent clipboard format with each message. 
Posting Post the WM_DDE_ADVISE message by calling the PostMessage function, not Send- 

Message. 

Allocate Options by calling the GlobalAlloc function with the GEMEM_DDE_SHARE 

option. 

Allocate altem by calling the GlobalAddAtom function. 

If the receiving (server) application responds with a negative WM_DDE_ACK message, 

the sending (client) application must delete the hOptions object. 

Receiving Post the WM_DDE_ACK message to respond positively or negatively. When posting 


WM_DDE_ACK, reuse the a/tem atom or delete it and create a new one. If the 
WM_DDE_ACK message is positive, delete the hOptions object; otherwise, do not delete 
the object. 


WM_DDE_DATA 


WM_DDE_DATA 


This message, posted by a server application, sends a data item value to the receiving 
(client) application, or notifies the client of the availability of data. 


Comments 


Parameter 


wParam 


[Param 


Description 
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Identifies the sending window. 


Identifies the available data and specifies how it is sent. 


Argument 


hData 


altem 


Description 


Low-order word of /Param. A handle 
that identifies the global memory object 
containing the data and additional infor- 
mation. The handle should be set to 
NULL if the server is notifying the client 
that the data item value has changed 
during a “warm link.” A warm link is es- 
tablished by the client sending a 
WM_DDE_ADVISE message with the 
{DeferUpd bit set. 


High-order word of /Param. An atom 
that identifies the data item for which 


data or notification is sent. 


The global memory object identified by hData consists of a DDEDATA data structure that 
contains the following: 


Word 
1 


Name 


fAckReq 


reserved 


Content 


If bit 15 is 1, the receiving (client) application 
is expected to send a WM_DDE_ACK message 
after the WM_DDE_DATA message has been 


processed. If bit 15 is zero, the client applica- 


tion should not send a WM_DDE_ACK 
message. 


Bit 14 is reserved. 
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Word Name Content 

fRelease If bit 13 is 1, the client application is expected 
to free the hData memory object after pro- 
cessing it. If bit 13 is zero, the client application 
should not free the object. See the “Posting” 
and “Receiving” sections for exceptions. 

fRequested If bit 12 is 1, this data is offered in response to a 
WM_DDE_REQUEST message. If bit 12 is 
zero, this data is offered in response to a 
WM_DDE_ADVISE message. 

reserved Bits 11-0 are reserved. 

2 cfFormat This specifies the format in which the data are 
sent or offered to the client application. It must 
be a standard or registered clipboard data for- 
mat. 

3-n Value[ ] This is the data. It is in the format specified by 
cfFormat. 

Posting Post the WM_DDE_DATA message by calling the PostMessage function, not SendMes- 
sage. 

Allocate hData by calling the GlobalAlloc function with the GMEM_DDESHARE option. 

Allocate altem by calling the GlobalAddAtom function. 

If the receiving (client) application responds with a negative WM_DDE_ACK message, 

the sending (server) application must delete the hData object. 

If the sending (server) application sets the fRelease flag to zero, the sender is responsible 

for deleting AData upon receipt of either a positive or negative acknowledgement. 

Do not set both the fAckReq and fRelease flags to zero. If both flags are set to zero, it is 

difficult for the sending (server) application to determine when to delete AData. 

Receiving If fAckReq is 1, post the WM_DDE_ACK message to respond positively or negatively. 


When posting WM_DDE_ACK, reuse the a/tem atom or delete it and create a new one. 
If fAckReq is zero, delete the altem atom. 


If the sending (server) application specified hData as NULL, the receiving (client) applica- 
tion can request the server to send the actual data by posting a WM_DDE_REQUEST 
message. 
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After processing the WM_DDE_DATA message in which hData is not NULL, delete 
hData unless either of the following conditions is true: 


m The fRelease flag is zero. 


m The fRelease flag is 1, but the receiving (client) application responds with a negative 
WM_DDE_ACK message. 


WM_DDE_EXECUTE 


Comments 


This message, posted by a client application, sends a string to a server application to be 
processed as a series of commands. The server application is expected to post a 
WM_DDE_ACK message in response. 


Parameter Description 
wParam Identifies the sending window. 
[Param Specifies the commands to be executed. 
Argument Description 
reserved The low-order word of /Param is re- 
served. 
hCommands High-order word of /Param. A handle 


that identifies a global memory object 
containing the command(s) to be ex- 
ecuted. 


The command string is null-terminated. The command string should adhere to the syntax 
shown below. Optional syntax elements are enclosed in double brackets ([[ ]]); single brack- 
ets ([ ]) are a syntax element. 


[opcodestring] [| [opcodestring] ] ... 
The opcodestring uses the following syntax: 
opcode] (parameter [| parameter ]] ... ) J] 


The opcode is any application-defined single token. It may not include spaces, commas, 
parentheses, or quotation marks. 


The parameter is any application-defined value. Multiple parameters are separated by com- 
mas, and the entire parameter list is enclosed in parentheses. The parameter may not in- 
clude commas or parentheses except inside a quoted string. If a bracket or parenthesis 
character is to appear in a quoted string, it must be doubled: ((. 
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The following examples show valid command strings: 


[connect ][download(queryl,results.txt) ]£disconnect] 
[query("sales per employee for each district")] 
CLopen("sample.xIm")J]Crun("ricl")] 


Posting Post the WM_DDE_EXECUTE message by calling the PostMessage function, not Send- 
Message. 


Allocate hCommands by calling the GlobalAlloc function with the 
GMEM_DDE_SHARE option. 


When processing WM_DDE_ACK sent in reply to WM_DDE_EXECUTE, the sender of 
the original WM_DDE_EXECUTE message must delete the hCommands object sent back 
in the WM_DDE_ACK message. 


Receiving Post the WM_DDE_ACK message to respond positively or negatively, reusing the hCom- 
mands object. 


WM_DDE_INITIATE 


This message, sent by either a client or server application, initiates a conversation with 
applications responding to the specified application and topic names. 


Upon receiving this message, all applications with names that match the aApplication 
application and that support the aTopic topic are expected to acknowledge it (see the 
WM_DDE_ACK message). 


Parameter Description 
wParam Identifies the sending window. 
[Param Specifies the target application and the topic. 
Argument Description 
aApplication Low-order word of /Param. An atom that 


specifies the name of the application 
with which a conversation is requested. 
The application name may not contain 
slashes or backslashes. These characters 
are reserved for future use in network im- 
plementations. If the application name is 
NULL, a conversation with all applica- 
tions is requested. 
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Parameter Description 

Argument Description 

aTopic High-order word of /Param. An atom 
that specifies the topic for which a con- 
versation is requested. If the topic is 
NULL, a conversation for all available 
topics is requested. 

Comments If the aApplication argument is NULL, any application may respond. If the aTopic argu- 


ment is NULL, any topic is valid. Upon receiving a WM_DDE_INITIATE request with a 
null topic, an application is expected to send a WM_DDE_ACK message for each of the 
topics it supports. 


Sending Send the WM_DDE_INITIATE message by calling the SendMessage function, not the 
PostMessage function. Broadcast the message to all windows by setting the first para- 
meter of SendMessage to —1, as shown: 


SendMessage(-1,WM_DDE_INITIATE,hwndClient ,MAKELONG(aApp,aTopic)); 


If the application has already obtained the window handle of the desired server, it can send 
WM_DDE_INITIATE directly to the server window by passing the server’s window 
handle as the first parameter of SendMessage. 


Allocate aApplication and aTopic by calling GlobalAddAtom. 


When SendMessage returns, delete the aApplication and aTopic atoms. 


Receiving To complete the initiation of a conversation, respond with one or more WM_DDE_ACK 
messages, where each message is for a separate topic. When sending WM_DDE_ACK 
message, create new aApplication and aTopic atoms; do not reuse the atoms sent with the 
WM_DDE_INITIATE message. 


WM_DDE_POKE 


This message, posted by a client application, requests the receiving (server) application to 
accept an unsolicited data item value. 


The receiving application is expected to reply with a positive WM_DDE_ACK message if 
it accepts the data, or with a negative WM_DDE_ACK message if it does not. 
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Parameter Description 
wParam Identifies the sending window. 
[Param Identifies the data and specifies how it is sent. 
Argument Description 
hData Low-order word of /Param. A handle 
that specifies the global memory object 
containing the data and other informa- 
tion. 
altem High-order word of /Param. An atom 
that identifies the data item offered to the 
server application. 
Comments The global memory object identified by hData consists of a DDEPOKE data structure that 
contains the following: 
Word Name Content 
1 reserved Bits 15-14 are reserved. 
fRelease If bit 13 is 1, the receiving (server) application 


is expected to free the memory object after pro- 
cessing it. If bit 13 is zero, the receiving 
application should not free the object. See the 
following “Posting” and “Receiving” sections 
for exceptions. 


reserved Bits 12-0 are reserved. 
2 cfFormat This specifies the client’s preferred type of data. 
It must be a standard or registered clipboard 
data format. 
3-n Value[ ] This is the data. It is in the format specified by 
cfFormat. 
Posting Post the WM_DDE_POKE message by calling the PostMessage function, not SendMes- 


sage. 
Allocate hData by calling the GlobalAlloc function with the GMEM_DDESHARE option. 
Allocate altem by calling the GlobalAddAtom function. 
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If the receiving (server) application responds with a negative WM_DDE_ACK message, 
the sending (client) application must delete the hData object. 


If the sending (client) application sets the fRelease flag to zero, the sending application 
must delete hData upon receiving either a positive or negative WM_DDE_ACK message. 


Receiving Post the WM_DDE_ACK message to respond positively or negatively. When posting 
WM_DDE_ACK, reuse the a/tem atom or delete it and create a new one. 


After processing the WM_DDE_POKE message, delete Data unless either of the follow- 
ing conditions is true: 
m The fRelease flag is zero. 


= The fRelease flag is 1, but the receiving (server) application responds with a negative 
WM_DDE_ACK message. 


WM_DDE_REQUEST 


This message, posted by a client application, requests the receiving (server) application to 
provide the value of a data item. 


Parameter Description 
wParam Identifies the sending window. 
[Param Specifies the requested data and the clipboard format number for 
the data 
Argument Description 
cfFormat Low-order word of /Param. A standard 
or registered clipboard format number. 
altem High-order word of /Param. An atom 
that specifies which data item is being re- 
quested from the server. 
Posting Post the WM_DDE_REQUEST message by calling the PostMessage function, not Send- 
Message. 


Allocate altem by calling the GlobalAddAtom function. 
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WM_DDE_TERMINATE 


Receiving 


If the receiving (server) application can satisfy the request, it responds with a 
WM_DDE_DATA message containing the requested data. Otherwise, it responds with a 
negative WM_DDE_ACK message. 


When responding with either a WM_DDE_DATA or WM_DDE_ACK message, reuse the 
altem atom or delete it and create a new one. 


WM_DDE_TERMINATE 


Posting 


Receiving 


This message, posted by either a client or server application, terminates a conversation. 


Parameter Description 
wParam Identifies the sending window. 
lParam Is reserved. 


Post the WM_DDE_TERMINATE message by calling the PostMessage function, not 
SendMessage. 


While waiting for confirmation of the termination, the sending application should not ac- 
knowledge any other messages sent by the receiving application. If the sending application 
receives messages (other than WM_DDE_TERMINATE) from the receiving application, it 
should delete any atoms or shared memory objects accompanying the messages. 


Respond by posting a WM_DDE_TERMINATE message. 


WM_DDE_UNADVISE 


This message, sent by a client application, informs a server application that the specified 
item, or a particular clipboard format for the item, should no longer be updated. This termi- 
nates the warm or hot link for the specified item. 

Parameter Description 

wParam Identifies the sending window. 


[Param Specifies the data-request item to be canceled. 
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Posting 


Receiving 


Parameter Description 


Argument Description 


altem High-order word of /Param. An atom 
that specifies the data for which the up- 
date request is being retracted. When 
altem is NULL, all active 
WM_DDE_ADVISE conversations as- 
sociated with the client are to be 
terminated. 


cfFormat Low-order word of /Param. The clip- 
board format of the item that specifies 
the clipboard format for which the up- 
date request is being retracted. When 
c{fFormat is NULL, all active 
WM_DDE_ADVISE conversations for 
the item are to be terminated. 


Post the WM_DDE_UNADVISE message by calling the PostMessage function, not Send- 
Message. 


Allocate altem by calling the GlobalAddAtom function. 


Post the WM_DDE_ACK message to respond positively or negatively. When posting 
WM_DDE_ACK, reuse the a/tem atom or delete it and create a new one. 
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Appendix A 
Virtual-Key Codes 


The following list shows the symbolic constant names, hexadecimal values, and 
descriptive information for Microsoft Windows virtual-key codes. The codes are 
listed in numeric order. 


Name Value Description 
VK_LBUTTON 01H Left mouse button 
VK_RBUTTON 02H Right mouse button 
VK_CANCEL 03H Used for control-break processing 
VK_MBUTTON 04H Middle mouse button (3-button 
mouse) 
05H-07H Undefined 
VK_BACK 08H BACKSPACE key 
VK_TAB 09H TAB key 
OAH-OBH Undefined 
VK_CLEAR OCH CLEAR key 
VK_RETURN ODH RETURN key 
VK_SHIFT 10H SHIFT key 
VK_CONTROL 11H CONTROL key 
VK_MENU 12H MENU key 
VK_PAUSE 13H PAUSE key 
VK_CAPITAL 14H CAPITAL key 
15H-19H Reserved for Kanji systems 
1AH Undefined 
VK_ESCAPE 1BH ESCAPE key 
1CH-1FH Reserved for Kanji systems 
VK_SPACE 20H SPACEBAR 
VK_PRIOR 21H PAGE UP key 
VK_NEXT 22H PAGE DOWN key 
VK_END 23H END key 
VK_HOME 24H HOME key 
VK_LEFT 25H LEFT ARROW key 


VK_UP 26H UP ARROW key 
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Name Value Description 
VK_RIGHT 27H RIGHT ARROW key 
VK_DOWN 28H DOWN ARROW key 
VK_SELECT 29H SELECT key 
2AH OEM specific 
VK_EXECUTE 2BH EXECUTE key 
VK_SNAPSHOT 2CH PRINTSCREEN key for Windows 
version 3.0 and later 
VK_INSERT 2DH INSERT key 
VK_DELETE 2EH DELETE key 
VK_HELP 2FH HELP key 
VK_O 30H 0 key 
VK_1 31H 1 key 
VK_2 32H 2 key 
VK_3 33H 3 key 
VK_4 34H 4 key 
VK_S 35H 5 key 
VK_6 36H 6 key 
VK_7 37H 7 key 
VK_8 38H 8 key 
VK_9 39H 9 key 
3AH-40H Undefined 
VK_A 41H A key 
VK_B 42H B key 
VK_C 43H C key 
VK_D 44H D key 
VK_E 45H E key 
VK_F 46H F key 
VK_G 47H G key 
VK_H 48H H key 
VK_I 49H I key 
VK_J 4AH J key 
VK_K 4BH K key 
VK_L 4CH L key 
VK_M 4DH M key 
VK_N 4EH N key 


VK_O 4FH O key 
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Name Value Description 
VK2P 50H P key 
VK_Q 51H Q key 
VK_R 52H R key 
VRS 53H S key 
VK_T 54H T key 
VK_U 55H U key 
VK_V 56H V key 
VK_W 57H w key 
VK_X 58H X key 
VK_Y 59H Y key 
VK_Z SAH Z key 

5BH-5FH Undefined 
VK_NUMPADO 60H Numeric key pad 0 key 
VK_NUMPAD1 61H Numeric key pad 1 key 
VK_NUMPAD2 62H Numeric key pad 2 key 
VK_NUMPAD3 63H Numeric key pad 3 key 
VK_NUMPAD4 64H Numeric key pad 4 key 
VK_NUMPADS5 65H Numeric key pad 5 key 
VK_NUMPAD6 66H Numeric key pad 6 key 
VK_NUMPAD7 67H Numeric key pad 7 key 
VK_NUMPAD8 68H Numeric key pad 8 key 
VK_NUMPAD9 69H Numeric key pad 9 key 
VK_MULTIPLY 6AH Multiply key 
VK_ADD 6BH Add key 
VK_SEPARATER 6CH Separater key 
VK_SUBTRACT 6DH Subtract key 
VK_DECIMAL 6EH Decimal key 
VK_DIVIDE 6FH Divide key 
VK_F1 70H Fl key 
VK_F2 71H F2 key 
VK_F3 72H F3 key 
VK_F4 73H F4 key 
VK_F5 74H F5 key 
VK_F6 75H F6 key 
VK_F7 76H F7 key 
VK_F8 77H F8 key 
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VK_NUMLOCK 
VK_OEM_SCROLL 


VK_OEM_1 


VK_OEM_PLUS 
VK_OEM_COMMA 
VK_OEM_MINUS 
VK_OEM_PERIOD 
VK_OEM_2 


VK_OEM_3 


VK_OEM_4 
VK_OEM_5 
VK_OEM_6 
VK_OEM_7 


VK_OEM_8 


VK_OEM_102 


80H-87H 
88H-8FH 
90H 

91H 
92H-B9H 
BAH 


BBH 
BCH 
BDH 
BEH 
BFH 


COH 


C1H-DAH 
DBH 


DCH 


DDH 


DEH 


DFH 


EQH-E1H 
E2H 


E3H-E4H 


Description 


F9 key 

F10 key 

Fil key 

F12 key 

F13 key 

F14 key 

F15 key 

F16 key 

OEM specific 
Unassigned 
NUM LOCK key 
SCROLL LOCK key 
Unassigned 


Keyboard-specific punctuation key 
(may not appear on every keyboard) 


Plus (+) key 
Comma (,) key 
Minus (-) key 
Period (.) key 


Keyboard-specific punctuation key 
(may not appear on every keyboard) 


Keyboard-specific punctuation key 
(may not appear on every keyboard) 


Unassigned 


Keyboard-specific punctuation key 
(may not appear on every keyboard) 


Keyboard-specific punctuation key 
(may not appear on every keyboard) 


Keyboard-specific punctuation key 
(may not appear on every keyboard) 


Keyboard-specific punctuation key 
(may not appear on every keyboard) 


Keyboard-specific punctuation key 
(may not appear on every keyboard) 


OEM specific 


<> or \l on enhanced, non-U.S. 
IBMo-compatible 102-key keyboard 


OEM specific 


Name 


E6H 

E7H-E8H 
E9H-F5H 
F6H-FEH 


Description 


Unassigned 
OEM specific 
Unassigned 
OEM specific 
Unassigned 
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Appendix B 
RC Diagnostic Messages 


This appendix contains descriptions of diagnostic messages produced by the 
Resource Compiler (RC). Many of these messages appear when the Resource 
Compiler is not able to compile your resources. The descriptions in this appendix 
can help you determine the problem. 


A (V) symbol at the beginning of a message description indicates that the 
message is displayed only if RC is run with the -V (verbose) option. These 
messages are generally informational and do not necessarily indicate errors. 


See Chapter 8, “Rescource Script Statements,” for information on the key words 
and fields specified in this appendix. 


The messages are listed in alphabetical order. 


Accelerator Type required (ASCII or VIRTKEY) 
The type field in the ACCELERATORS statement must contain either the 
ASCII or VIRTKEY value. 

BEGIN expected in Accelerator Table 
The BEGIN key word must immediately follow the ACCELERATORS 
key word. 

BEGIN expected in Dialog 
The BEGIN key word must immediately follow the DIALOG key word. 


BEGIN expected in menu 
The BEGIN key word must immediately follow the MENU key word. 


BEGIN expected in RCData 
The BEGIN key word must immediately follow the RCDATA key word. 


BEGIN keyword expected in String or Error Table 


The BEGIN key word must immediately follow the STRINGTABLE or 
ERRTABLE key word. 


Cannot Reuse String Constants 


You are using the same value twice ina STRINGTABLE or ERRTABLE 
statement. Make sure you are not mixing overlapping decimal and hexadecimal 
values. 
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Control Character out of range [*A - 4Z] 
A control character in the ACCELERATORS statement is invalid. The 
character following the caret (4) must be between A and Z, inclusive. 
copy of temp-file-2 to exe-file failed 
The temporary file was not able to create the new .EXE file. Make sure that the 
TEMP environment variable is pointing to a drive that is not write-protected. 
Copying segment id (size bytes) 
(V) RC is copying the specified segment to the .EXE file. 


Could not find RCPP.EXE 
RCPP.ERR must be in the current directory or a directory in the PATH environ- 
ment. 

Could not open in-file-name 
RC could not open the specified file. Make sure the file exists and that you typed 
the filename correctly. 

Couldn’t open resource-name 
RC could not open the specified file. Make sure the file exists and that you typed 
the filename correctly. 

Couldn’t write executable 


The .EXE file could not be copied to the temporary file. Make sure that the 
TEMP environment variable is pointing to a drive that is not write-protected and 
that the .EXE file from the linker is correct. You can check the .EXE file with the 
EXEHDR program. 

Creating resource-name 


(V) RC is creating a new .RES file. 


Empty menus not allowed 


An END key word appears before any menu items are defined in the MENU 
statement. Empty menus are not permitted by the Resource Compiler. Make sure 
you do not have any open quotation marks within the MENU statement. 


END expected in Dialog 


The END key word must occur at the end of a DIALOG statement. Make sure 
there are no open quotes left from the preceding statement. 
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END expected in menu 


The END key word must come at the end of a MENU statement. Make sure you 
do not have any open quotation marks or a mismatched pair of BEGIN and END 
statements. 

Error: Bitmap file resource-file is not in 3.00 format. 


Use SDKPaint to convert version 2.x resource files to the 3.0 format. 


Error Creating resource-name 
Could not create specified .RES file. Make sure it is not being created on a read- 
only drive. Use the —V option to find out whether the file is being created. 
Error: I/O error reading file. 


Read failed. Since this is a generic routine, no specific filename is supplied. 


Error: I/O error seeking in file 


Seeking in file failed. 


Error: I/O error writing file. 


Write failed. Since this is a generic routine, no specific filename is supplied. 


Error: Old DIB in resource-name. Pass it through SDKPAINT. 


The resource file specified is not compatible with Windows 3.0. Make sure you 
have read and saved this file using the latest version of SDKPaint. 


Error: Out of memory. Try not using resources with string identifiers. 


There is not enough memory to allocate for a table of string names. You can 
view these names are when you use the —V option. Try to replace the string 
names with numbers. For example, you can change 


MYICON ICON myicon.ico 

to 

ak ICON myicon.ico 

or provide the following statement in your header file: 


dtdefine MYICON 1 


Error: Resource file resouce-name is not in 3.00 format. 


Make sure your icons and cursors have been read and saved using the latest 
version of SDKPaint. 
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Errors in .EXE file 


LINK failed. See the CodeView and Utilities manual in the Microsoft C 5.1 
Optimizing Compiler documentation set for more information. 


.EXE file too large; relink with higher /ALIGN value 


The EXE file is too large. Relink the .EXE file with a larger /ALIGN value. If 
the .EXE file is larger than 800K, you should use the /ALIGN:32 value on your 
LINK line. 


-EXE not created by LINK 


You must create the .EXE file with a version of LINK that is from C version 5.1 
or later. 


Expected Comma in Accelerator Table 


RC requires a comma between the event and idvalue fields in the ACCEL- 
ERATORS statement. 


Expected control class name 


The class field of a CONTROL statement in the DIALOG statement must be 
one of the following types: BUTTON, COMBOBOX, EDIT, LISTBOX, 
SCROLLBAR, STATIC, or user-defined. Make sure the class is spelled correctly. 


Expected font face name 


The typeface field of the FONT option in the DIALOG statement must be an 
ASCII character string enclosed in double quotation marks. This field specifies 
the name of a font. 


Expected ID value for Menuitem 


The MENU statement must contain a menulD field, which specifies the name or 
number that identifies the menu resource. 


Expected Menu String 


Each MENUITEM and POPUP statement must contain a text field, which is a 
string enclosed in double quotation marks that specifies the name of the menu 
item or pop-up menu. A MENUITEM SEPARATOR statement requires no 
quoted string. 


Expected numeric command value 


RC was expecting a numeric idvalue field in the ACCELERATORS statement. 
Make sure you have used a #define constant to specify the value and that the con- 
stant is spelled correctly. 
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Expected numeric constant in string table 
A numeric constant, defined in a #define statement, must immediately follow the 
BEGIN key word in a STRINGTABLE or ERRTABLE statement. 
Expected numeric point size 
The pointsize field of the FONT option in the DIALOG statement must be an in- 
teger point size value. 
Expected Numerical Dialog constant 
A DIALOG statement requires integer values for the x, y, width, and height 
fields. Make sure these values are included after the DIALOG key word and that 
they are not negative. 
Expected String in STRINGTABLE/ERRTABLE 
A string is expected after each stringid value ina STRINGTABLE or 
ERRTABLE statement. 
Expected String or Constant Accelerator command 
RC was not able to determine what kind of key is being set up for the accel- 
erator. The event field in the ACCELERATORS statement might be invalid. 
Expecting number for ID 
Expecting a number for the id field of a control statement in the DIALOG state- 
ment. Make sure you have a number or #define statement for the control ID. 
Expecting quoted string in dialog class 
The class field of the CLASS option in the DIALOG statement must be an in- 
teger or a string, enclosed in double quotation marks. 
Expecting quoted string in dialog title 
The captiontext field of the CAPTION option in the DIALOG statement must 
be an ASCII character string enclosed in double quotation marks. 
File not found: fileame 


The file specified in the RC command line was not found. Check to see whether 
the file has been moved to another directory and whether the filename or 
pathname is typed correctly. 

Font names must be ordinals 


The pointsize field in the FONT statement must be an integer, not a string. 
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Gangload area is [size] bytes at offset 0x[address] 
(V) This is the size (in bytes) of all the segments that have one of the following 
attributes: 
m PRELOAD 
= DISCARDABLE 
= Code segments that contain the entry point, WinMain 
= Data segments (which should not be discardable) 
The segments are placed in a continguous area in the .EXE file for fast loading. 
The offset value is from the the beginning of the file. To disable gangloading, use 
the —k option. 
Insufficient memory to spawn RCPP.EXE 
There wasn’t enough memory to run the preprocessor (RCPP). You can try not 
running any memory-resident software that might be taking up too much 
memory. Use the CHKDSK program to verify the amount of memory you have. 
Invalid Accelerator 
An event field in the ACCELERATORS statement was not recognized or was 
more than two characters in length. 
Invalid Accelerator Type (ASCII or VIRTKEY) 
The type field in the ACCELERATORS statement must contain either the 
ASCII or VIRTKEY value. 
Invalid control character 
A control character in the ACCELERATORS statement is invalid. A valid con- 
trol character consists of one letter (only) following a caret (4). 
Invalid Control type 


Each control statement in a DIALOG statement must be one of the following: 
CHECKBOX, COMBOBOX, CONTROL, CTEXT, DEFPUSHBUTTON, 
EDITTEXT, GROUPBOX, ICON, LISTBOX, LTEXT, PUSHBUTTON, 
RADIOBUTTON, RTEXT, SCROLLBAR. 


Make sure these control statements are spelled correctly. 


Invalid .EXE file 


The .EXE file is invalid. Make sure that the linker created it correctly and that 
the file exists. You can check the .EXE file with the EXEHDR program. 
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Invalid switch, option 
You used an option that was not valid. Use RC —? for a list of the command-line 
options. 

Invalid type 
The resource type was not among the types defined in the WINDOWS.H file. 


Invalid usage. Use re —? for Help 
Make sure you have at least one filename to work with. Use RC —? for a list of 
the command-line options. 

No executable filename specified. 


The -FE option was used, but no .EXE filename specified. 


No resource binary filename specified. 


The -FO option was used, but no .RES filename specified. 


Not a Microsoft Windows format .EXE file 
Make sure that the linker created the .EXE file correctly and that the file exists. 
You can check the .EXE file with the EXEHDR program. 

Out of far heap memory 


There wasn’t enough memory. Try not running any memory-resident software 
that might be taking up too much space. Use the CHKDSK program to find out 
how much memory you have. 

Out of memory, needed n bytes 


RC was not able to allocate the specified amount of memory. 


RC: Invalid swap area size: —S string 


Invalid swap area size. Check your syntax for the -S option on the RC command 
line. The following are acceptable command lines: 


RG S123 
RC S123K ;where K is kilobytes 
RC S123p ;where p is paragraphs 
RC: Invalid switch: option 
You used an option that was not valid. Use RC —? for a list of the command-line 
options. 
RC: RCPP preprocessor-command-string 
(V) RC is passing the specified string to the preprocessor. 
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RC: RCPP.ERR not found 
RCPP.ERR must be in the current directory or a directory in the PATH environ- 
ment. 

RC terminated by user 
A CONTROL+C key combination was pressed, terminating RC. 


RC terminating after preprocessor errors . 
See the Microsoft C 5.1 Optimizing Compiler documentation for information 
about preprocessor errors. 

RCPP.EXE command line greater than 128 bytes 


The command line was too long. 


RCPP.EXE is not a valid executable 
RCPP.EXE is not valid. The file might have been altered. Try copying the file 
from the SDK disks. 

Reading resource-name 
(V) RC is reading the .RES file. 


Resources will be aligned on number byte boundaries 
(V) The alignment is determined by the ALIGN:number option on the LINK 
line. 

Sorting preload segments and resources into gangload section 


(V) RC is sorting the preloaded segments so that they can be loaded quickly. 


Text string or ordinal expected in Control 


The text field of a CONTROL statement in the DIALOG statement must be 
either a text string or an ordinal reference to the type of control is expected. If 
using an ordinal, make sure that you have a #define statement for the control. 


The EXETYPE of this program is not Windows 


The EXETYPE WINDOWS statement did not appear in the .DEF file. Since the 
linker might make optimizations for OS/2 (the default EXETYPE) that are not 
appropriate for Windows, the EXETYPE WINDOWS statement must be 
specified. 


Unable to create destination 


RC was not able to create the destination file. Make sure there is enough disk 
space. 
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Unable to open exe-file 


RC could not open this .EXE file. Make sure that the linker created it correctly 
and that the file exists. 


Unbalanced Parentheses 


Make sure you have closed every open parenthesis in the DIALOG statement. 


Unexpected value in RCData 


The raw-data values in the RCDATA statement must be integers or strings, each 
separated by a comma. Make sure you did not leave out a comma or leave out a 
quotation mark around a string. 


Unknown DIB header format 


The bitmap header is not a BITMAPCOREHEADER or BITMAPINFO- 
HEADER structure. 


Unknown error spawning RCPP.EXE 


For an unknown reason, RCPP was not started. Try copying the file from the 
SDK disks, and use the CHKDSK program to verify the amount of available 
memory. 


Unknown Menu SubType 


The item-definition field of the MENU statement can contain only MENUITEM 
and POPUP statements. 


Warning: ASCII character not equivalent to virtual key code 


There is an invalid virtual-key code in the ACCELERATORS statement. The 
ASCII value for some characters (such as *, 4, &,) is not equivalent to the virtual- 
key code for the corresponding key. (In the case of the asterisk (*), the virtual- 
key code is equivalent to the ASCII value for 8, the numeric character on the 
same key. Therefore the statement 


VIRTIKEY ** 
is invalid.) See Appendix A, “Virtual-Key Codes,” and Appendix D, “Character 
Tables,” for these values. 


Warning: Discardable segment id (hex-size bytes) is excessively large. 


The segment is greater than 27FFh in size. RC displays this warning because 
very large segments can adversely affect memory usage. Check your map file 
listing for the exact size of your segments. 
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Warning: SHIFT or CONTROL used without VIRTKEY 


The ALT, SHIFT, and CONTROL options apply only to virtual keys in the 
ACCELERATORS statement. Make sure you have used the VIRTKEY option 
with one of these other options. 


Writing resource resource-name or ordinal-id resource type (resource size) 
(V) RC is writing the resource name or ordinal ID, followed by a period and the 
resource type and size (in bytes). 

Warning: string segment number set to PRELOAD 


RC displays this warning when it copies a segment that must be preloaded but 
that is not marked PRELOAD in the linker .DEF file. 


All nondiscardable segments should be preloaded, including automatic data 
segments, fixed segments and the entry point of the code (WinMain). 


The attributes of your code segments are set by the .DEF file. Check your map 
file listing for more information. 


Appendix C 
Windows Debugging Messages 


The debugging version of Microsoft Windows generates diagnostic messages 
whenever it encounters an error that would otherwise cause the system to fail. 
Each diagnostic message has a unique number or string that identifies the cause 
of the message and potential failure. This appendix lists most of the diagnostic 
message names, their corresponding hexadecimal value, explains the meaning of 
each message, and in some cases suggests possible solutions. 


The messages are divided into three sections that correspond to the three 
Windows modules: User, GDI, and Kernel. The messages in each section are pro- 
duced by a function that is contained in the respective module. This division is 
necessary only because some messages in the User and GDI modules have the 
same error code. 


User Error Codes 


The error codes in this section are created by functions in the Windows User 
module. Some of these messages use the same codes as do GDI messages. Check 
the context of the error code to determine which module it is associated with. See 
the next section, “GDI Error Codes” for more information on differentiating 


these messages. 
Code Meaning 
1 Not enough memory was available for the requested allocation. Ask for a smaller 


amount of memory. Check HEAPWALK to see how much memory is free. 
Make sure you are not creating fixed objects that are fragmenting memory. 


2 Not enough memory was available for the requested reallocation. Do not attempt 
to call the LocalRealloc function to increase the size of your segment beyond 
64K. Avoid creating fixed objects that fragment memory. Make sure that the 
object is not discardable. 


4 The memory block could not be locked. Make sure the return value from your 
allocation function is a valid handle. Check HEAPWALK to see how much 
memory is free. Make sure you are not creating a fixed object that is fragmenting 
the memory. 


5 The memory block could not be unlocked. Make sure the block was locked to 
begin with. 
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16 


17 


An invalid handle was passed to a GDI function. This could occur for any GDI 
object. Check the value you obtain from the Create/Get GDI object to make sure 
it returned a valid value. 


The handle to the window you passed to the function was not valid. Use the 
IsWindow function to verify that the handle is valid and that the window has not 
been destroyed. 


The five preallocated display contexts (DCs) are in use. Make sure your 
application calls the ReleaseDC function to release a DC when the application is 
done with it. If ReleaseDC is not called, the DC will not be available to the 
system or any application. 


The DefWindowProc function was not found in your application. Place the 
DefWindowProc function in your application and make sure you are passing the 
correct parameters. 


Some other application may have left the clipboard open. Pause and check again 
in a few seconds. Make sure your application calls the CloseClipboard function 
as soon as possible. Do not leave the clipboard open. 


Your application attempted to destroy a window while it was still using a display 
context (DC). Make sure your application calls the ReleaseDC function to 
release a DC when the application is done with it. If ReleaseDC is not called, the 
DC will not be available to the system or any application. 


The keyboard driver did not initialize correctly. Rerun Setup. 


The mouse driver did not initialize correctly. Rerun Setup, or make sure that the 
mouse hardware did not get disconnected and that it is working outside of 
Windows. 


The display driver did not initialize correctly. Rerun Setup. 


An attempt was made to unlock the data segment but it wasn’t locked. Make sure 
the data segment is locked before trying to unlock it. 


The counter for windows of a particular class exceeded the limit of 32,767. Each 
time a window of a particular class is created, Windows increments a class usage 
counter. Each time a window of that class is destroyed, the counter is 
decremented. This message occurs in a CreateWindow or CreateWindowEx 
function. 


The counter for windows of a particular class became a negative number. See the 
preceding message for details. This message occurs in a DestroyWindow 
function. 


18 
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The counter for windows of a particular class was not zero when the class was 
destroyed. When an application or library terminates, Windows destroys all 
windows and classes created by that application or library. This error occurs if 
after the class is destroyed there still exists a window created by a different 
application or library that used the destroyed class. 


GDI Error Codes 


GDI errors occur when an invalid handle is passed to certain GDI functions. 
These errors can be identified by the existence of ValidateHandle in the back- 
trace. ValidateHandle is an internal Windows function that ensures that a handle 
is valid. Make sure you check for this function in order to differentiate GDI er- 
rors from User errors that have the same code number. (User messages are de- 
scribed in the previous section.) 


Meaning 
A GDI function received a NULL object handle. 


A valid handle is referencing an object that is not a valid GDI object or is a GDI 
object of the wrong type. This error often occurs when an object is deleted and 
the handle is reused for some other purpose in another GDI operation. 


The value of the error code depends on the type of object expected by the GDI 
function that generated the error. Each GDI object has a type identifier. Each 
GDI function that accepts an object as a parameter determines which object or 
objects are acceptable. To ensure that the handle it receives is valid, the GDI 
function calls ValidateHandle and passes it the handle and a range of acceptable 
type identifiers. If the handle references an object whose type identifier does not 
fall in the acceptable range, ValidateHandle generates an error code representing 
the lowest value of the range. 


For example, the SelectObject expects its first parameter to be a DC, a metafile 
DC, or and banding metafile DC. It passes this value, along with the range (7H to 
AH) to ValidateHandle. If the type identifier of the handle is not within that 
range, ValidateHandle produces an error code with the value 7H. 


The following list shows the type identifier of various objects: 


1 Pen 

2 Brush 
3 Font 

4 Palette 
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Type ID Object 
5 Bitmap 
6 Region 
7 Device context 
8 Disabled device context 
9 Metafile device context 
A Banding metafile device context 
B A window being destroyed had not released a DC that was obtained using the 
GetDC function. 


Kernel! Error Codes 


The diagnostic messages in this section are associated with functions contained 
in the Windows Kernel module. These messages are listed in numerical order. 
Some numbers represent multiple messages. The retail version of Windows 
displays both the code number and the message text. The debugging version of 
Windows displays only the code number. 


Code Message 


FF gnotify - can’t discard segment 


This error is usually caused in real mode by a far call when the DS register is 
pointing to a fixed object. Windows will not be able to discard the code segment 
that made the call. 


This error can be produced by the following functions: GlobalReAlloc, 
GlobalAlloc (the wFlags parameter cannot contain GMEM_NOCOMPACT or 
GMEM_NODISCARD), GlobalCompact, GlobalDiscard, GlobalWire. 


FF Cannot GetProcAddress a task 


You cannot use the GetProcAddress call for a library or the calling task. 


FF MakeProcinstance only for current instance 
This message is displayed if you use MakeProcInstance to call the entry point 
of another task. 

FF MyOpenFile not reentrant 


Internal Windows error. 
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FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


gadd_free: Seg add not in range 


Unable to add segment to global free list. Your application has stepped over 
Windows’ memory. 


FREE MEMORY OVERWRITE AT 


Memory listed as free does not contain CC in each byte as expected. Put a break 
point at the specified address to find the problem. 


free_list: prev bad 


The free global memory list was corrupted by a wild write; the pointer from the 
previous entry in list does not point to the current entry. 


free_list: next bad 


The free global memory list was corrupted by a wild write; the pointer in the next 
entry does not point back to current entry. 


free_list: count bad 


The free global memory list was corrupted by a wild write; the final entry in the 
list does not match expected final entry. 


Heap frozen in INT 3F. 

Internal Windows error. 

LOCAL FREE MEMORY OVERWRITE AT 

The memory listed as free does not contain CC in each byte as expected. 
Automatic Data Segment larger than 64K. 


STACK + HEAP + STATICS combined are greater than 64K. Change the mod- 
ule-definition (.DEF) file. 


PatchCodeHandle, CORE DUMP FOLLOWS: 


Internal Windows error. 


Iru: prev bad 


The free global memory list was corrupted by a wild write; the pointer from the 
previous entry in the list does not point to current entry. 


Iru: next bad 


The free global memory list was corrupted by a wild write; the pointer in the next 
entry does not point back to the current entry. 
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FF Iru: count bad 


The free global memory list was corrupted by a wild write; the final entry in the 
list does not match the expected final entry. 


100 LocalAlloc : Invalid local heap 


A wild write corrupted the local heap. 


100 Ifreeadd : Invalid local heap 
Unable to add segment to the local free list. Your application has overwritten the 
local heap. 

100 function_name: Invalid local heap 


Lists the function at which the check is occurring (LocalAlloc, LocalLock, etc.) 
and generally indicates an overwrite of the local heap list. 


103 Invalid local heap 


Either a wild write occurred or the LocalInit function was not performed cor- 
rectly. Leave some memory for Windows when calling LocalInit. 


140 Local heap is busy 


Two edit controls in the same dialog with the same ID value. Make sure that you 
don’t interchange decimal and hexadecimal numbers. 


140 EnterCrit: local heap is busy 
Internal Windows error. Attempting to reenter critical section of local memory 
manager. 

140 LeaveCrit: local heap is NOT busy 


Internal Windows error. Attempting to leave critical section of local memory 
manager when not already in critical section. 


143 Invalid local heap 
14B Invalid local heap 
15B Invalid local heap 
180 LDREF: Invalid local handle 


A local handle (produced in calls to LocalReAlloc, LocalLock, etc.) is invalid. 


1C0 LocalLock: Object usage count overflow 


LMEM_MOVEABLE or LMEM_DISCARDABLE memory was locked more 
than the limit of 255 times. 


1F0 


1F0 


200 


200 


200 


200 


240 
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LocalFree: freeing locked object 

Local memory was not unlocked before LocalFree was called. 
LocalUnlock: Object usage count underflow 

Local memory was unlocked more times than it was locked. 
gmovye_stack usage error 

Internal Windows error using temporary stack. 

Leave_eems_stack error 

Internal Windows error using temporary stack. 

function_name: Invalid global heap,offender_para_reader_header 


Lists the function at which check is occurring (&n = GlobalAlloc, GlobalLock, 
etc.) and generally indicates overwrite of local heap list. 


function_name: Invalid global heap,offender_para_reader_header 


Lists the function where check failed and generally indicates overwrite of local 
heap list. 


If DX is nonzero, DX = offending arena header: 


Code Meaning 

201 Forward links invalid 

202 Backward links invalid 

204. ga_handle points to free handle 

208 Arena points to handle 

280 ga_sig is bad 

If DX is 0: 

Code Meaning 

210 Allocated handles don’t match used handles 
220 Total number of handles don’t match up 
240 Total number of free handles does not match up 


Critical section problems 
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280 gdref: invalid handle 


Global handle (produced in calls to GlobalReAlloc, GlobalLock, etc.) is invalid. 
Make sure you: 


m= Have a window procedure for the window. 
= DoaMakeProclInstance call for the window procedure. 


= Export your window procedure. 


2C0 GlobalLock: Object usage count overflow 


GMEM_MOVEABLE or GMEM_DISCARDABLE memory was locked more 
than the limit of 255 times. 


2F0 EMS_GlobalFree: freeing locked object 

Memory was not unlocked before GlobalFree was called. 
2F0 GlobalFree: freeing locked object 

Global memory was not unlocked before GlobalFree was called. 
2F0 GlobalFree: freeing locked object 

Global memory was not unlocked before GlobalFree was called. 
2F0 GlobalUnlock: Object usage count underflow 

Global memory was unlocked more times than it was locked. 
2F0 GlobalUnWire: Object usage count underflow 

Global memory was unwired more times than it was wired. 
303 PatchStack - invalid BP chain 

Stack frame chain was invalid due to a wild write. 
303 SearchStack - invalid BP chain 

Stack frame chain was invalid due to a wild write. 
401 BOOT: unable to load application 

LoadModule failed for the shell application. 
401 BOOT: Unable to find file pathname 


File not found. 
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401 


403 


404 


405 


406 


407 


408 
409 


409 


409 


BOOT: Invalid .EXE file pathname 
.EXE file format is invalid. 
BOOT: Unable to load pathname 


LoadModule failed for a library loaded during boot time. Pass a far pointer to 
the name of the module that could not be loaded. 


Invalid ordinal reference 


You have linked to a function that does not have an entry point in the version of 
Windows you are running. Check your .DEF file to make sure you are using the 
correct ordinal reference. 


Call to undefined dynlink entry point at entry-point 


A bad import table or wild write occurred over segment relocation table. This 
message is displayed when your application calls the ordinal entry point for a 
driver that no longer contains that ordinal. 


Invalid start procedure 

Bad EXE header. 

Invalid module handle 

Could not obtain EXE header for the specified module handle. 


Invalid relocation record in es,bx 


A wild write destroyed a relocation record. 

Error saving forward reference 

Out of memory loading segment from hModule of segment location 
Insufficient memory was available for loading segments. 

1/O error reading segment contents from Module of segment location 
Unable to read segment due to file open, read, or seek error. 

Segment contents invalid 


Checksum value did not match segment contents when loading a segment. 
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409 Segment contents trashed 
A wild write has occurred on the specified segment. 


Error 409 occurs when a code segment was changed after it was loaded; this is 
usually the result of a wild write. 


Running in the protected-mode version of Windows will cause a general protec- 
tion violation to occur on the code causing the violation. 


Check to make sure your buffers are large enough for the operation. Also, run 
Shaker to see if the problem occurs more frequently. 


410 Error reading relocation records from 


Int 21 function 3F was unable to read off the disk, or the information read is in- 
compatible with the information requested. 


411 Insert disk for specified file 


412 Unable to load non-resident name table 


When attempting to load the nonresident name table, one of the following four 
possible errors occurred: 


= OpenFile failed. 
@ Int 21 function 42 (seek) failed. 
= Int 21 function 3F (load seg) failed. 


= The table size is inconsistent with the contents. 


4FF INT 3F handler unable to load segment 


LoadSegment failed. You will receive an “Out of memory loading segment” 
message before you receive this message. 


501 Missing resource table 

502 Bad resource type 

503 Bad resource name 

504 Bad resource file 

505 Unable to read resource from segment 


Int 21 function 3F was unable to read off disk or the information read is incom- 
patible with the information requested. 
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505 Error loading from resource file filename 


This error has one of these possible causes: 


= The AResInfo parameter of LoadResource is NULL. 
= A wild write has destroyed the module header. 
= A wild write has destroyed the EXE table. 


u The resource file does not contain the resource requested. 


600 Atom Manager errors 


A wild write has occurred. 


700 Input/Output package errors 


Appendix D 


Character Tables 


IBM PC Extended Character Set 


128 
129 
130 
131 
132 
133 
134 
135 
136 
137 
138 
139 
140 
141 
142 
143 


144 
145 
146 
147 
148 
149 
150 
151 
152 
153 
154 
155 
156 
157 
158 
159 


a oo 


be ee a 


Indicates that this character is not supported by Windows. 
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Appendix E 
Windows 32-Bit Memory Management DLL 


One of the significant features of the Intel 80386 and 80486 microprocessors is 
the availability of 32-bit registers for the manipulation of code and data. Applica- 
tions written to use these registers can avoid the segmented memory model of ear- 
lier CPUs and instead use a “flat” memory model in which memory is viewed as 
a single, contiguous block. 


Although Microsoft Windows version 3.0 continues to adhere to a segmented 
memory model, Windows does provide a set of functions that allow an applica- 
tion to make use of the 32-bit capabilities of the 80386 and 80486 processors. 
These functions are available to an application through a dynamic-link library 
(DLL) named WINMEM32.DLL. This DLL is supplied as part of the SDK and is 
not part of the retail version of Windows. Consequently, if your application calls 
functions in WINMEM32.DLL, you must include WINMEM32.DLL with your 
application when you distribute it to your application’s end users. 


This appendix introduces the functions contained in WINMEM32.DLL and ex- 
plains how to use these functions in the context of a Windows application. It 
covers the following information: 


= A brief look at some of the differences between a segmented memory model 
and a flat memory model 


= Using WINMEM32.DLL to take advantage of the 32-bit capabilities of the 
80386 and 80486 processors 


= Programming considerations when using these capabilities ina Windows 
application 


= Common approaches for using 32-bit memory in a Windows application 


A directory of the functions supplied by WINMEM32.DLL follows this informa- 
tion. The appendix concludes with several assembly-language code examples il- 
lustrating how to use the DLL’s functions. 


IMPORTANT This appendix assumes that you are thoroughly familiar with the archi- 
tecture and code- and memory-management features of the 80386/80486 processors. This 
appendix does not attempt to explain these features, and assumes that you are familiar with 
the terminology and concepts associated with that architecture. 


Only experienced Windows-application developers with extensive experience writing as- 
sembly-level code should attempt to use these functions in an application. 
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E.1 Segmented and Flat Memory Models 


The 80x86 family of microprocessors implement a segmented memory model in 
which system memory is divided into 64K segments. In the native mode of these 
processors, the address of any byte consists of two 16-bit values: a segment 
address and an offset. In the protected mode of the 80286, 80386, and 80486 pro- 
cessors, the segment address is replaced by a selector value which the processor 
uses to access the 64K segment. In both modes, memory objects larger than 64K 
will occupy all or part of several segments. An application cannot access these 
objects as though they consist of a single contiguous block simply by in- 
crementing a pointer to the memory. Instead, the application can increment only 
the offset portion of the address, taking care not to exceed the 64K boundary of 
the segment. 


The 80386 processor introduced 32-bit registers that parallel the 16-bit registers 
of older members of the 80x86 family. These registers make it possible for the 
first time to access memory in segments larger than 64K. In fact, the maximum 
segment size is potentially so large (2°~ bytes) that a flat memory model utilizing 
a single segment is now feasible. In this model, an application’s code and/or data 
occupies a single segment. The application can manipulate the 32-bit offset por- 
tion of the memory as though it were a simple pointer. The application can incre- 
ment and decrement the pointer/offset throughout the address space without 
having to deal with multiple segment boundaries. 


To a certain extent, then, the flat memory model most closely resembles the tiny 
memory model in which both code and data occupy a single segment; except, of 
course, that the segment is much larger than the 64K limit imposed by the seg- 
mented memory model. As in the tiny memory model, the beginning of the seg- 
ment of the flat memory model can appear anywhere in memory. In other words, 
the segment-descriptor portion of the address can refer to virtually any location 
in memory. As the application moves through memory, the segment descriptor 
never changes. Only the offset is incremented and decremented to point to differ- 
ent locations in memory. 


As this appendix will note, it is not possible to implement a Windows application 
using an exclusively flat memory model. Windows itself relies on the 16-bit seg- 
mented memory model, and so any application that interacts with Windows must 
implement at least one 16-bit code segment. Despite this limitation, however, it 
is possible for a Windows application to reside largely in one or more 32-bit code 
segments and to use 32-bit data segments. The WINMEM32.DLL library makes 
this possible in a way that ensures the application will cooperate fully with 
Windows and similar platforms. 
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E.2 Using the WINMEMS32.DLL Library 


Although you could directly implement flat memory model code in your 
Windows application, this implementation would necessarily be unique to your 
application. As a result, your application might not run with future versions of 
Windows or with other compatible platforms. 


WINMEM32.DLL supplies a standard method for implementing a flat memory 
model that is guaranteed to run with future versions of Windows and other com- 
patible platforms. It gives your application access to services for allocating, real- 
locating, and freeing 32-bit memory objects; for translating 32-bit pointers to 
16-bit pointers that can be used by Windows and DOS functions; and for aliasing 
a data segment to a code segment so you can execute code loaded into a 32-bit 
segment. 


Your application can load WINMEM32.DLL when Windows is running in real, 
standard, or 386 enhanced mode. However, since the 32-bit registers of the 
80386/80486 processor are available only when Windows is in 386 enhanced 
mode, WINMEM32.DLL is enabled only in that mode. If your application can 
run in real or standard mode, you must design your application so that it can 
access 16-bit memory instead of 32-bit memory in these modes. You can deter- 
mine the mode in which Windows is running by calling the GetWinFlags 
function. 


WINMEM322.DLL contains eight functions that enable your application to access 
32-bit memory. The following list summarizes each of these functions: 


Function Description 

Global32Alloc Allocates a block of 32-bit memory. 

Global32Realloc Changes the size of a 32-bit memory object. 

Global32Free Frees a 32-bit memory object. 

Global16PointerAlloc Converts a 32-bit pointer to a 16-bit pointer. 

Global16PointerFree Frees a pointer alias created by 
Global16PointerAlloc. 

Global32CodeAlias Creates a code alias for a 32-bit memory ob- 
ject, allowing code in the the object to be 
executed. 

Global32CodeAliasFree Frees a code alias created by 
Global32CodeAlias. 

GetWinMem32Verwsion Returns the version number of the 


WINMEM32.DLL API. 
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A directory listing of these functions appears later in this appendix. 


WINMEM32.DLL is a standard Windows DLL, and so your application loads it 
as it would any other DLL. In addition to the DLL, the SDK provides the 
C-language WINMEM32.H include file to declare the functions in your applica- 
tion, and the import library WINMEM32.LIB to allow your application to import 
the functions of the DLL when you link your application. 


The calling convention of the WINMEM32.DLL functions is the same as for 
other Windows functions. The DLL entry points are external FAR PASCAL pro- 
cedures. They preserve SS, BP, DS, SI, and DI, and they return values in AX or 
DX:AX. 


E.3 Considerations for Using 32-Bit Memory 


As previously noted, Windows adheres to the segmented memory model. That is, 
all far pointers are in the form 16:16 consisting of a 16-bit segment address (in 
real mode) or selector (in protected mode), combined with a 16-bit offset within 
the segment. An application using the 32-bit registers of the 80386/80486 proces- 
sor cannot directly call the Windows functions because its far pointers are in the 
form 16:32 and Windows cannot deal with the extra 16 bits in the offset portion 
of the address. 


Because of this conflict, a Windows application cannot reside exclusively in a 32- 
bit segment. It must contain at least one 16-bit “helper” code segment through 
which it interacts with Windows (including WINMEM32.DLL). In other words, 
all calls to Windows functions must be made in the helper code segment. The 
helper segment contains the code that converts the 16:32 pointers in the 32-bit 
segment to the 16:16 pointers used by Windows functions. This segment also per- 
forms the same tasks for the application when the application is making calls to 
DOS, to other DLLs, and to any other code that exclusively uses 16:16 pointers. 


An important limitation on this helper segment is that it must not be discardable. 
If the segment were discarded and a 32-bit segment were to attempt to access the 
segment, an indirect call into the Windows kernel module to reload the segment 
would result. Since the source of this indirect call would not be a 16-bit segment, 
the system might crash. 


Another important consideration is that your application must not assume any- 
thing about the state of the 32-bit registers around 16:16 API calls. For instance, 
the Windows API calls preserve SI and DI, but they presently do not preserve 
ESI and EDI. If the application wants to preserve 32-bit registers around 16:16 
API calls, it must explicitly push and pop the register values around the calls. If 
the 32-bit code segment that calls a Windows function (via the helper segment) 
assumes that ESI and EDI will be preserved when the Windows function returns, 
the helper segment must explicitly save the registers before making the actual 
Windows function call. The helper segment must then restore the registers when 
the Windows function returns. 
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This rule also applies to return values when a 32-bit segment indirectly calls a 
Windows function and the caller expects a 32-bit return value. The helper 
segment must explicitly set the high-order 16 bits of the return value when it 
moves it into the EAX register, as shown in the following examples: 


MOVEZX EAX , AX 3; Unsigned return 
MOVESX EAX , AX ; Signed return 


All these considerations apply equally to calls to Windows DLLs, DOS, and 
other 16-bit APIs. 


E.3.1 The Flat Model Under Windows 


In the Windows environment, system memory is a shared resource which 
Windows manages on behalf of all applications. For this reason, a true flat 
memory model is not possible in the Windows environment. When an applica- 
tion allocates 32-bit memory in Windows, the memory that Windows gives the 
application can be located anywhere in physical memory. The memory to which 
the selector refers is specific to the application and does not include system-wide 
memory locations. In other words, the selector that the application receives does 
not refer to interrupt vector 0. This means that offset 400h for the selector does 
not point to the DOS ROM BIOS data area, for example. 


E.3.2 The Application Stack 


Windows has problems operating in an environment of mixed segment types 
(both 16:16 and 16:32 segments). As a result, the stack selector size must match 
the corresponding code selector size. In other words, when the processor is ex- 
ecuting code in a 16:32 (USE32) code segment, the selector in the SS register 
must also be 16:32. And when code in a 16:16 (USE 16) segment is executing, 
the SS register must contain a 16:16 selector. 


When the 80386/80486 processor is executing on a USE16 stack segment, it uses 
the low-order 16 bits of the ESP register as the SP register. Since only the lower 
16 bits are of use when the processor is executing on a USE16 stack segment, it 
does not control how the upper 16 bits of the ESP register are set. As a result, the 
upper 16 bits are set at random. When an application switches to a USE32 stack 
segment, the ESP register will contain a corrupted pointer unless the high 16 bits 
of ESP are set properly. 


For example, a Windows application has a USE32 code segment and a USE16 
helper segment, but (improperly) only a USE32 stack. When the application calls 
from its USE32 code into the USE16 segment, it stays on its USE32 stack. The 
USE16 code segment calls a Windows function, which changes the selector in 
the SS register to a USE16 selector. Since the stack is now USE16, the upper 16 
bits of the ESP register are set at random. The code that originally switched 
stacks then restores the original selector in SS and, not knowing that it referred to 
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a USE32 stack, restores the 16-bit SP register instead of the full 32 bits of the 
ESP register. As a result, the USE32 stack now has an invalid pointer in the ESP 
register. 


There are a number of ways to deal with this problem. First, an application can 
maintain two separate stacks, one USE16 and the other USE32. Maintaining sepa- 
rate stacks requires you to include extra code —for example, you must copy para- 
meters for stack-calling conventions such as C. Another solution would be to 
maintain one stack but two stack selectors, again one USE16 and the other 
USE32. Both selectors would point to the same USE32 memory. This would re- 
quire the USE32 stack to be restricted to ESP values less than or equal to FFFFh. 


In either case, the USE16 code segment must switch to the USE32 stack immedi- 
ately before calling into a USE32 code segment. When control returns from the 
USE32 code segment to the USE16 code segment, the USE16 segment must im- 
mediately switch back to the USE16 stack before doing anything else. 


Since the problem with stack switching is the corruption of the high 16 bits of 
ESP, a Windows application with 16:32 code must make sure that it sets the high 
16 bits of ESP when it is switching onto the USE32 stack selector. It sets these 
bits by placing the selector into SS, as shown in the following example: 


MOV SS,word ptr [Use32StackSel] 
MOV ESP,dword ptr [Use32StackOffset] 


MOV SS,word ptr [Use32StackSel] 
MOVZX ESP,word ptr [Use32StackOffset] 


MOV SS,word ptr [Use32StackSel] 
MOVZX ESP,SP 


E.3.3 Interrupt-Time Code 


Because Windows is a 16-bit environment, Windows has problems dealing with 
a mixed code-type environment, a 32-bit code segment in a Windows application 
must not contain code that is executed at interrupt time. Also, it must not contain 
data that is accessed at interrupt time. Any code executed at interrupt time must 
be in a USE16 code segment running on a USE16 stack. Data used at interrupt 
time must be USE16 data. This rule also applies to processor exceptions (such as 
the coprocessor exception) since they are handled like interrupts. Note, however, 
that it is acceptable for a 32-bit code segment to access data in a USE16 data 
segment. 
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E.3.4 Programming Languages 


As should be obvious by now, the helper segment has to perform very low-level 
tasks to manage transitions between USE16 and USE32 stacks, and between 
USE16 and USE32 code. For this reason, it is difficult to use a high-level lan- 
guage such as C to write the helper segment code. Even if you were to write the 
helper segment in C, you would have to add assembly-language support for the 
more difficult tasks. In most cases, then, it is easier and more efficient to write 
the entire helper segment in assembly language. 


E.4 Using 32-Bit Memory in a Windows Application 


There are three common uses for 32-bit memory in a Windows application. In in- 
creasing order of complexity, they are: 


@ Using 32-bit data objects in 16-bit code 
Using 32-bit code and data in a subroutine library 


= Using 32-bit code and data for the main program 


The following sections briefly describe each of these approaches. 


E.4.1 Using 32-Bit Data Objects 


The simplest use of 32-bit memory is to store data that is used exclusively by 
USE16 code segments. In this case, the application contains no USE32 code 
segments and so does not require a dedicated helper segment. Instead, any (or 
all) of its code segments performs the necessary tasks of allocating, reallocating, 
and freeing the 32-bit memory. If data from the 32-bit memory is to be passed to 
Windows functions or other 16-bit functions, the application’s USE16 code seg- 
ment also performs the aliasing of 32-bit pointers to 16-bit pointers using the 
Global16PointerAlloc function. 
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E.4.2 Using 32-Bit Code and Data in a Subroutine Library 


Using 32-bit memory for code and data can simplify porting an application from 
a 32-bit platforms to the Windows environment when portions of the application 
can be isolated as a subroutine library. This subroutine library serves as a low- 
level engine, but does not call Windows or DOS functions. 


As when the 32-bit memory is used exclusively for data storage, the USE16 code 
segment retains control of the program. Typically, the USE16 segment allocates 
the 32-bit memory, creating one or more objects for code and data. In addition to 
the data-management tasks described in the previous section, the USE16 segment 
also loads the subroutine code into one of the 32-bit segments, fixes up the point- 
ers in the code as required, and creates a code-segment alias to permit the code to 
be executed. The USE16 code segment is responsible for maintaining control of 
the program flow, calling into the USE32 code segment when it requires the low- 
level services of the subroutine library. 


E.4.3 Using 32-Bit Code and Data for the Main Program 


The most complex use of 32-bit memory involves placing the primary control of 
the program in a 32-bit code segment. In this type of application, the USE16 seg- 
ment is reduced exclusively to helper status. During initialization, the USE16 seg- 
ment allocates the 32-bit memory for code and data, loads the code into the 
USE32 segment, creates a code-segment alias for the USE32 segment, and then 
calls the main entry point in the USE32 segment. 


From that point, the USE32 segment takes control of the program, calling into 
the USE16 helper segment only when the application needs to call Windows or 
DOS functions. The USE32 segment continues to control the flow of the pro- 
gram until the application is ready to terminate. Only then does it return control 
to the USE16 segment so the USE16 segment can free the 32-bit memory and 
perform other garbage collection before the application quits. 
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E.5 Functions Directory 


This section describes the functions in WINMEM32.DLL. Most of these func- 
tions return zero to indicate success or a nonzero error-code value to indicate 
failure. The following list describes these error codes. 


Value Meaning 


1 Invalid function. The current Windows mode does not support 
this function. Windows supports the 32-bit memory functions 
only in 386 enhanced mode. 


2 Invalid flags. The wF/ags parameter contained invalid bit set- 
tings. The wFlags parameter currently is not used and must be 
set to zero. 

3 Invalid parameter. One of the parameters was invalid. For ex- 


ample, a size parameter was out of range. 


4 Selector not available. There is not enough room in the descrip- 
tor table(s) to allocate the required selector(s). It may be 
necessary to advise the user to close other Windows applications. 


5 Insufficient memory. There is not enough memory to satisfy the 
requested allocation or reallocation. 
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GetWinMem32Version 


Syntax 


Return Value 


WORD GetWinMem32Version(_) 


This function returns the API version implemented by the DLL. This is not the version 
number of the DLL itself. 


This function has no parameters. 


The return value specifies the version of the 32-bit memory API implemented by 
WINMEM32.DLL. The high-order 8 bits contain the major version number, and the 
low-order 8 bits contain the minor version number. The current API version number 
is 1.00 (100h): the major version number is 1, and the minor version number is 0. 


Globali6PointerAlloc 


Syntax 


Return Value 


WORD = Global16PointerAlloc(wSelector, dwOffset, lpBuffer, dwSize, wF lags) 


This function converts a 16:32 pointer into a 16:16 pointer alias that the application can 
pass to a Windows function or other 16:16 functions. 


Parameter Type/Description 

wSelector WORD _ Specifies the selector of the object for which an alias is to 
be created. This must be the selector returned by a previous call to 
Global32Alloc. 

dwOffset DWORD Specifies the offset of the first byte for which an alias is 


to be created. The offset is from the first byte of the object specified 
by the wSelector parameter. Note that wSelector:dwOffset forms a 
16:32 address of the first byte of the region for which an alias is to be 
created. 


[pBuffer LPDWORD Points to a four-byte location in memory that re- 
ceives the 16:16 pointer alias for the specified region. 


dwSize DWORD _ Specifies the addressable size in bytes of the region for 
which an alias is to be created. This value must be in the range 1 to 
10000h. 


wFlags WORD Is reserved and must be set to zero. 


The return value is zero if the function was successful. Otherwise, it is one of the error 
codes described at the beginning of this section. 
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Comments 


Global16PointerFree 


When this function returns successfully, the location pointed to by the /pBuffer parameter 
contains a 16:16 pointer to the first byte of the region. This is the same byte to which 
wSelector:dwOffset points. 


The returned selector is a read/write, expand up, small (B bit clear) data descriptor. The 
descriptor DPL and the setting of granularity (the G bit) are at the discretion of the system, 
and so the application should not assume their settings. The descriptor DPL and the selec- 
tor RPL are appropriate for a Windows application. 


NOTE An application must not change the setting of any fields in the descriptor or the selector RPL. 
Doing so can result in a system crash and will prevent the application from running on compatible 
platforms. 


Because of tiling schemes implemented by some systems, the offset portion of the returned 
16:16 pointer is not necessarily zero. 


An application should not assume the size limit of the returned selector. Instead, an applica- 
tion should assume that at least dwSize bytes can be addressed starting at the 16:16 pointer 
created by this function. 


Global16PointerFree 


Syntax 


Return Value 


Comments 


WORD  Global16PointerFree(wSelector, dwAlias, wFlags) 


This function frees the 16:16 pointer alias previously created by a call to the 
Global16PointerAlloc function. 


Parameter Type/Description 

wSelector WORD _ Specifies the selector of the object for which the alias is to 
be freed. This must be the selector returned by a previous call to 
Global32Alloc. 

dwAlias DWORD _ Specifies the 16:16 pointer alias to be freed. This must 


be the alias (including the original offset) returned by a previous call 
to Global16PointerAlloc. 


wFlags WORD Is reserved and must be set to zero. 


The return value is zero if the function was successful. Otherwise, it is one of the error 
codes described at the beginning of this section. 


An application should free a 16:16 pointer alias as soon as it is no longer needed. Freeing 
the alias releases space in the descriptor table, a limited system resource. 
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Global32Alloc 


Syntax 


Return Value 


Comments 


WORD = Global32Alloc(dwSize, lpSelector, dwMaxSize, wF lags) 


This function allocates a block of memory to be used as a USE32 code or data segment 
and retrieves the selector portion of the 16:32 address of the memory block. The first byte 
of the object is at offset 0 from this selector. 


Parameter Type/Description 

dwSize DWORD _ Specifies the initial size in bytes of the block to be allo- 
cated. This value must be in the range of 1 to 4000000h (64 
megabytes). 

IpSelector LPWORD Points to a two-byte location in memory that receives 


the selector portion of the 16:32 address of the allocated object. 


dwMaxSize DWORD _ Specifies the maximum size in bytes that the object will 
reach when it is reallocated by the Global32Realloc function. This 
value must be in the range of 1 to 4000000h (64 megabytes). If the 
application will never reallocate this block of memory, the dwMax- 
Size parameter should be set to the same value as the dwSize 
parameter. 


wFlags WORD Is reserved and must be set to zero. 


The return value is zero if the function was successful. Otherwise, it is one of the error 
codes described at the beginning of this section. 


If the Global32Alloc function fails, the value to which /pSelector points is zero. If the 
function succeeds, /pSelector points to the selector of the object. The valid range of offsets 
for the object referenced by this selector is in the range of 0 to (but not including) dwSize. 


The returned selector is a read/write, expand-up, big (B bit set), data descriptor. The 
descriptor DPL and the setting of granularity (the G bit) are at the discretion of the system; 
the application should not assume these settings. Since the system sets the granularity, the 
actual size of the object (and the selector size limit) may be greater than the requested size 
by up to one byte less than 4K. The descriptor DPL and the selector RPL will be appro- 
priate for a Windows application. 


NOTE An application must not change the setting of any fields in the descriptor or the selector RPL. 
Doing so can result in a system crash and will prevent the application from running on compatible 
platforms. 
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Global32CodeAlias 


The allocated object is neither moveable nor discardable, but can be paged. Since page 
locking an object is useful only if the object contains code or data that is used at interrupt 
time, and since 32-bit memory cannot be used at interrupt time, an application should not 
page lock a 32-bit memory object. 


Global32CodeAlias 


Syntax 


Return Value 


Comments 


WORD  Global32CodeAlias(wSelector, IpAlias, wFlags) 


This function creates a 16:32 (USE32) code alias selector for a 32-bit memory object pre- 
viously created by the Global32Alloc function. This allows the application to execute 
code contained in the memory object. 


Parameter Type/Description 

wSelector WORD _ Specifies the selector of the object for which an alias is to 
be created. This must be the selector returned by a previous call to 
Global32Alloc. 

IpAlias LPWORD Points to a two-byte location in memory that receives 


the 16:32 code-segment alias selector for the specified object. 


wFlags WORD Is reserved and must be set to zero. 


The return value is zero if the function was successful. Otherwise, it is one of the error 
codes described at the beginning of this section. 


If the function fails, the value pointed to by the /pAlias parameter is zero. If the function is 
successful, /pAlias points to a USE32 code-segment alias for the object specified by the 
wSelector parameter. The first byte of the object is at offset 0 from the selector returned in 
IpAlias. Valid offsets are determined by the size of the object as set by the most recent call 
to the Global32Alloc or Global32Realloc function. 


The returned selector is a read/execute, nonconforming, USE32 (D bit set) code descriptor. 
The descriptor DPL and the setting of granularity (the G bit) are at the discretion of the sys- 
tem, and so the application should not assume their settings. The granularity will be con- 
sistent with the current data selector for the object. The descriptor DPL and the selector 
RPL are appropriate for a Windows application. 


NOTE An application must not change the setting of any fields in the descriptor or the selector RPL. 
Doing so can result in a system crash and will prevent the application from running on compatible 
platforms. 
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An application should not call this function more than once for an object. Depending on 
the system, the function might fail if an application calls it a second time for a given object 
, without first calling the Global32CodeAliasFree function for the object. 


Global32CodeAliasFree 
Syntax WORD  Global32CodeAliasFree(wSelector, wAlias, wFlags) 


This function frees the USE32 code selector alias previously created by a call to the 
Global32CodeAlias function. 


Parameter Type/Description 

wSelector WORD Specifies the selector of the object for which the alias is to 
be freed. This must be the selector returned by a previous call to 
Global32Alloc. 

wAlias WORD Specifies the USE32 code selector alias to be freed. This 


must be the alias returned by a previous call to Global32CodeAlias. 


wFlags WORD Is reserved and must be set to zero. 


Return Value The return value is zero if the function was successful. Otherwise, it is one of the error 


codes described at the beginning of this section. 


Global32Free 
Syntax WORD = Global32Free(wSelector, wF lags) 


This function frees an object previously allocated by the Global32Alloc function. 


Parameter Type/Description 


wSelector WORD Specifies the selector of the object to be freed. This must 
be the selector returned by a previous call to Global32Alloc. 


wF lags WORD Is reserved and must be set to zero. 


Return Value The return value is zero if the function was successful. Otherwise, it is one of the error 


codes described at the beginning of this section. 
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Comments 


Global32Realloc 


This function frees the object itself, as well as all aliases created for the object by the 
32-bit memory API. 


NOTE Before terminating, an application must call this function to free each object allocated by 
Global32Alloc to ensure that all aliases created for the object are freed. 


Global32Realloc 


Syntax 


Return Value 


Comments 


WORD  Global32Realloc(wSelector, dwNewSize, wFlags) 


This function changes the size of a 32-bit memory object previously allocated by the 
Global32Alloc function. 


Parameter Type/Description 


wSelector WORD _ Specifies the selector of the object to be changed. This 
must be the selector returned by a previous call to Global32Alloc. 


dwNewSize DWORD Specifies the new size in bytes of the object. This value 
must be greater than zero and less than or equal to the size specified 
by the dwMaxSize parameter of the Global32Alloc function call that 
created the object. 


wFlags WORD Is reserved and must be set to zero. 


The return value is zero if the function was successful. Otherwise, it is one of the error 
codes described at the beginning of this section. 


If this function fails, the previous state of the object is unchanged. If the function succeeds, 
it updates the state of the object and the state of all aliases to the object created by the 
32-bit memory API. For this reason, an application must call the Global32Realloc to 
change the size of the object. Using other Windows functions to manipulate the object will 
result in corrupted aliases. 


This function does not change the selector specified by the wSelector parameter. If this 
function succeeds, the new valid range of offsets for the selector is in the range of 0 to (but 
not including) dwNewSize. 


The system determines the appropriate granularity of the object. As a result, the actual size 
of the object (and the selector size limit) may be greater than the requested size by up to 
one byte less than 4K. 
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.386p 
memS equ 1 
XU USIt 
include cmacros.inc 


; NOTE that we CANNOT use the normal CMACROS segment macros: 


: CreateSeg 
: sBegin 

sEnd 
; because since we are .386p the default segment type is USE32. Our segments 


; need to be USE16 so we have to declare our segements manually so that the 
; USE16 segment attribute is included. 


include windows.inc 
wt 
; These equates would normally be in an app specific include file 


error_bad_file  EQU @8@01h 
error_wrong_mode EQU O80G02h 


; External WINMEM32 Procedures 


externFP GetWinMem32Version 


externFP Global32Al1loc 
externFP Global32Realloc 
externFP Global32Free 

externFP Global16PointerAlloc 
externFP Globall6PointerFree 
externFP Global32CodeAlias 
externFP Global32CodeAliasFree 


; External Windows Procedures 


externFP OpenFile 
externFP GetWinFlags 
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externFP _llseek 
externFP _lread 
externFP _lclose 
externFP OemToAnsi 


; MANUAL VERSION OF: createSeg _HELPERCODE,hcode,word,public,CODE 


; NOTE that this segment MUST NOT BE DISCARDABLE, it should be fixed. 


This is because the segment is called by USE32 code. 


_HELPERCODE segment word public 'CODE' usel6 


_HELPERCODE ends 


2 


; MANUAL VERSION of the automatic data segment declaration 


_DATA 
_DATA 


_DATA 


globa 


global 


global 


globa 


global 


2 


S: 
e 


S 


D 
D 


D 


D 


D 


egment word public 'DATA' usel6 
nds 


egment usel6 


AddrOEMToANSI ,@ ; Address of OEMToANSI helper function 
AddrDOSGetFreeSpace,@ ; Address of DOS Get disk Free space 

‘ helper function 
U32RetVal ,@ ; Return code from USE32 cal] 
U1l6StackAlias,@ ; Alias for the stack 
EntryStackSave,@ ; stack ptr save location 


; This FWORD forms the entry point for the USE32 code 


U32EntryPt LABEL FWORD 

globalD U32EntOff ,@WG1GGBGh ; Entry assumed at offset 64K 
globalW U32CodeSel ,@ ; CODE alias for the BIG object 
globalW U32DataSel ,@ ; DATA selector for the BIG object 
_DATA ends 


HELPERCODE segment usel6 


assume cs:_HELPERCODE 


a KKK KKK KK KKK KKK KKK KEKE KKK KKK KEK KK KEK KKK KR KK KKK KKK KKK KKK KKK KKK KEKE KK KKK KKK KEKKEKKEKE 
’ 


; SetupCal1USE32 


SetupCal1USE32(fName) 


Setup and call into USE32 code 
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; ASSUMPTIONS: 

; The USE32 Image is a @ ORGed 32 bit code image with NO HEADER. 

: The first 64k of the image (offsets QOBBOBOG-GOOOFFFFh) is reserved 
; for the stack. We put the stack here so that the required stack 

: switching (USE32<->USE16) is simply a matter of changing SS. 


: The entry point of the USE32 code is assumed to be right after the 
: stack at offset @@G@1900Hh in the image. We enter with DS, FS, GS 
: and SS set to the FLAT data segment, and CS set to the flat code 
; segment. It is the responsibility of the USE32 entry point to set 
; ES AND PRESERVE IT FOR US. 


: When this code wishes to call the two provided USE16 helper routines, 
; it looks up the call addresses in the AddrOEMToANSI and 

: AddrDOSGetFreeSpace variables in the _DATA segment. 

: This "loader" code actually needs to pass the selector for the 

: _DATA segment to the USE32 code so that it can access the data 

: segment, or it needs to copy the call addresses into the USE32 

: code/data segment. This detail of the implementation is NOT 

: included in this code. 


; ENTRY: 

: FName - DWORD pointer to file name of USE32 image to load 
SEX Te 

: AX != @ If an error occurs 

: AX = error code 

° Else 

$ AX = @ and U32RetVal contains the return code from the 
; USE32 code. 

* USES: 

| C Standard 


KEKE KKK KEK KKK KKK KKK KKK KKK KKK KKK KERR RK RK K KKK KKK KKK KKK KKK RK KEKE KKK KKK KKKKEKKKEKE 
2 


cProc StartupCal1USE32,<FAR,PUBLIC>,<si,di> 
ParmD fName 


LocalD§ fSize ; Size of file 

LocalD Ul16RdAlias ; Alias for reading image 

LocalD FileOff ; Current file offset for read 
LocalW fHand ; File handle 

LocalV OpnBuf,<SIZE OPENSTRUC> ; Open file struct for openfile call 


cBegin 
assume ds:_DATA 
assume es:nothing 
assume ss:_DATA 
; First check if we are running in enhanced mode 


; NOTE THAT SINCE WE DO NOT KNOW AS YET WHAT MODE WE ARE IN WE NEED 


2 


’ 
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TO AVOID USING 386 SPECIFIC INSTRUCTIONS 


cCall GetWinFlags 


and ax,WF_PMODE + WF_ENHANCED 

cmp ax,WF_PMODE + WF_ENHANCED 

je short OKtoLoad ; MUST BE SHORT 
mov ax,error_wrong_mode 

jmp Donel 


We now know we are in the proper mode and that 386 instructions 
are now OK. 


OKtoLoad: 


, 


2 


’ 


; Set up the addresses for the USE32 code to call the helper routines 


mov ax,cs 

mov word ptr [AddrOEMToANSI+2],ax 

mov word ptr [CAddrOEMToANSI],offset _HELPERCODE: U320EMtoANSI 

mov word ptr [AddrDOSGetFreeSpace+2] ,ax 

mov word ptr [AddrDOSGetFreeSpace],offset _HELPERCODE:U32GetDskFree 


Open the file 


lea bx ,OpnBuf 
regptr ssbx,ss,bx 
cCall OpenFile,<fName,ssbx,OF_READ> 


cmp ax,-1l ; Did we find it? 
je DonelFleErr ; No, file error 
mov fHand,ax ; Save file handle 


; Get file size 


cCall _llseek,<fHand,9,9,2> 


shl edx,16 

mov dx ,ax 

inc edx 

jz DonelFleErr ; seek failed, file error 

dec edx 

mov fSize,edx 

cmp edx , 1899Gh ; Image is at least 64k? 

jbe DonelFlErr ; No, size is too small, file error 


; Move file pointer back to start of file for read 


cCall _llseek,<fHand,@,0,@> 


; Allocate big USE32 object 


mov si,dataOffset U32DataSel 
regptr Selpt,ds,si 
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cCall Global32Alloc,<fSize,Selpt,fSize,@> 
or ax,ax ; Worked? 
jnz FcloseEr ; No, return WINMEM32 error code 


; Allocate USE16 stack alias for first 64K of object 


mov si,dataOffset Ul6StackAlias 

regptr Alipt,ds,si 

mov ecx , G9O1GGGGh ; 64K 

cCall Global16PointerAlloc,<[U32DataSel1],9,0,Alipt,ecx,@> 

or ax,ax ; Worked? 

jnz AliasErrF3 ; No, return WINMEM32 error code 


; Allocate USE32 code alias 


mov si,dataOffset U32CodeSel 

regptr Alipt,ds,si 

cCall Global32CodeAlias,<{U32DataSel],Alipt,@> 

or ax,ax ; Worked? 

jnz AliasErrF2 ; No, return WINMEM32 error code 


; Now read in the image. We will do this in 32K hunks. 


mov FileOff,@ ; Starting at file offset @ 
ReadLp: 

mov ecx ,WVBOBOGOh 3 ek 

cmp ecx, fSize 

jbe short Read32k 

mov ecx, fSize 


Read32k: 
; Make a USE16 alias for this region of the object 
push eCcx 
lea si,U1l6RdAlias 
regptr Alipt,ss,si 
ecail] Global16PointerAlloc,<[U32DataSel],FileOff,Alipt,ecx,@> 


pop ecx 

or ax,ax 

jnz short AliasErrFl 

push eCx 

cCall _lread,<fHand,Ul6RdAlias,cx> 
push ax 

cCal] Globall6PointerFree,<{U32DataSel],U1l6RdAlias,@> 
pop ax 

pop ecx 

inc ax 

jz short F1RdErr 

dec ax 

cmp ax,Cx 

jne short F1RdErr 


add FileOff,ecx 
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sub fSize,ecx 
ja short ReadLp 


; We are now ready to set up and call into the USE32 code 


Save the current stack so we can switch to the USE32 stack 


NOTE CAREFULLY THAT THIS MAKES THIS ROUTINE NON-REENTRANT 
SINCE IT SAVES THE CURRENT SS:SP IN A STATIC MEMORY LOCATION. 


mov word ptr CEntryStackSave],sp 
mov word ptr [CEntryStackSave+2],ss 
mov ax, [U32DataSel ] 

push ds 

pop es 


assume es:_DATA 


; Set up all the segs, and call into USE32 
; NOTE that we just leave the file open across the call. 


mov ds,ax 
assume ds:nothing 
mov fs,ax 
mov gs,ax 
mov SS,ax 
assume ss:nothing 
MOV esp, QOGOFFFCh 


call [U32EntryPt] 
; Recover DS and stack. 


2 


mov Dx,es 

mov ds ,bx 
assume ds:_DATA 

mov ss,word ptr [EntryStackSavet2] 
assume ss:_DATA 

mov sp,word ptr [EntryStackSave] 


; 
; Set success return and clean up. 


mov [U32RetVal],eax 
xor ax,ax ; Return success 
jmp short AliasErrFl 
FIRdErr: 
mov ax,error_bad_file 


AliasErrFl: 


; Free USE32 code alias 


push ax ; Save error code 
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cCall Global32CodeAliasFree,<[U32DataSel],[U32CodeSel],@> 
pop ax 
AliasErrF2: 


? 


; Free USE16 stack alias 


push ax ; Save error code 
cCall Globall6PointerFree,<({U32DataSel],[U16StackAlias],@> 
pop ax 


AliasErrF3: 


’ 


; Free the object 


> 


push ax ; Save error code 
cCall Global32Free,<([U32DataSel],@> 
pop ax 


FcloseEr: 


; Close the file 


, 


push ax ; Save error code 
cCall _lclose,<fHand> 
pop ax 
jmp short Donel 
DonelFilErr: 
mov ax,error_bad_file 
Donel: 
cEnd 


SKK KKK KKK KK KKK KKK KKK KKK KE KKK RK KKK KERR KKK KKK KEK KKK KKK KKK RK EKER KEK KKK KKKKKKEKKKKKEK 
, 


; U320EMtoANSI - Call OemToANSI from USE32 segment 
$ Assumes PASCAL calling convention 


; ENTRY: 
: U320EMtoANSI(1pOemStr,1pAnsiStr) 


; NOTE that these pointer arguments are NOT really LPSTRs. They 
' are near pointers into the USE32 data object (implied segment 
; is U32DataSel ) 


PEK Ts 
- EAX is return code 


USES 
: 32 bit C Standard 


KEK KEKE KEK KEKE KK KEK KERR KE KKK RK KEK KKK KKK KKK ERK K KKK KEK KEK KEE KEKE RRR KK KKKKKKKEKKKKKK 
? 


PUBLIC U320EMtoANSI 
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(RT EE TO I ET SES SI SSS 


U320EMtoANSI proc far 
assume ds:nothing 
assume es:nothing 
assume ss:nothing 


; First switch to the USE16 stack 


mov cx,ds ; Save entry DS in cx till we get the stack switched 
mov ax,SEG _DATA 
mov ds,ax 
assume ds:_DATA 
mov ss,word ptr [U16StackAlias+2] 
push e@Cx ; Entry DS, as DWORD to keep stack aligned 
push ebp 
mov bp,sp 


; Frame now looks like this: 


: dword ptr [bp + 20] --> First arg to OEMToANSI JpOemStr (actually a 32 
bit near pointer) 

3 dword ptr [bp + 16] --> Second arg to OEMToANSI IpAnsiStr (actually a 32 
bit near pointer) 


: dword ptr [bp + 12] --> Return CS 
; dword ptr [bp + 8] --> Return EIP 
: dword ptr [bp + 4] --> Entry DS pushed as DWORD 
; dword ptr [bp + 9] ==? ‘BotpyEBP 
}pOemStr equ dword ptr [bp+2] 
}pAnsiStr equ dword ptr [bp+16] 
sub sp,8 ; Need two LPSTRs for the aliases 
AlsOemStr equ dword ptr [bp-4] ; Alias for 1pOemStr 
AlsAnsiStr equ dword ptr [bp-8] ; Alias for IpAnsiStr 
push esi 
push edi 
push ebx 
push es ; Preserve "flat" ES, FS, GS 
push fs 
push gs 


There is a ?, how BIG is 1pOemStr? Need to know this to set the 
size of the alias(s). What we will do is "cheat". We will set 
the size to 64k (or size to end of USE32 object, whichever is 
smaller). NOTE that this assumes that the string is <= 64K which 
is a reasonable assumption since we can't alias something larger 
than that anyway. 


1s] eax,dword ptr [U32DataSel] ; Get limit of USE32 object 
inc eax 2 ACMI => saize 
mov edx,eax 
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sub eax, 1pOemStr ; Number of bytes to end of USE32 object 

jc SkipCal] ; Bad string ptr 

sub edx, ]pAnsiStr ; Number of bytes to end of USE32 object 

Ale short SkipCall ; Bad string ptr 

cmp eax,edx 

jbe short UseSrcLim 

mov eax,edx ; lpAnsiStr is closer to end of object 
UseSrcLim: 

mov ecx ,OGG18GGGh ; 64k 

cmp ecx , eax 

jbe short Use64k 

mov ecx,eax ; Limited by size to end of object 


Use64k: 
; Create Alias for lpOemStr 
push eCx 
lea bx,AlsOemStr 
regptr AlsPt,ss,bx 


cCall Global1l6PointerAlloc,<[{U32DataSel],1pOemStr,AlsPt,ecx,@> 


pop eCX 
or ax,ax 
jnz short SkipCall 


; Create Alias for lpAnsiStr 
lea bx,AlsAnsiStr 
cCall Globall6PointerAlloc,<[U32DataSel],]pAnsiStr,AlsPt,ecx,@> 


or ax,ax 
jnz short FreeQemAls 


; Call OemToAnsi 

cCal] OemToAnsi ,<AlsOemStr,AlsAnsiStr> 
; Free the aliases 

push ax ; Save RET code 


cCall Globall6PointerFree,<[U32DataSel],AlsAnsiStr,@> 


pop ax ; Restore RET code 
FreeOemAls: 
push ax ; Save RET code 


cCall Globall6PointerFree,<({U32DataSel],AlsOemStr,@> 


pop ax ; Restore RET code 
SkipCall: 
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pop 
pop 
pop 
pop 
pop 
pop 
add 
pop 
pop 


gs 

fs 

es 

ebx 

edi 

esi 

sp,8 

ebp 

eCx ; Entry DS in CX 


; Sign extend the return to make it 32 bit 


mMOVSX e@ax,ax 


; Switch back to the USE32 stack MAKING SURE TO SET HIGH 16 BITS OF ESP. 


mov 


ss,[U32DataSel ] 


MOVZX esp,sp 


mov 

assume 
db 
ret 


ds,cx 

ds:nothing 
66h ; USE32 override on far ret so it returns to EIP 
(2 * 4) 


U320EMtoANSI endp 


KKK KR KKK KK KK KKK KKK KKK KKK KKK KKK KK KK KKK KK KK KKK KKK KKK KKK KEKE KEK KKK KKK KKK EKER EK 
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; U32GetDskFree - Issue DOS call to get disk free space 


: Assumes PASCAL calling convention 


; ENTRY: 

rane 9 BS 

: EAX 
; EAX 
» USES: 


U32GetDskFree(drvnum) 


= Disk free space in bytes 
== QFFFFFFFFh if error 


32 bit C Standard 


KK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK RK KK KKK KKK KK KK KKK KKK KKK KKK KKK KEK KK KKK KRKEKKEEE 
’ 


PUBLIC U32GetDskFree 


U32GetDskFree proc far 


assume 
assume 
assume 
; 

Py ETrst 


ds:nothing 
es:nothing 
ss:nothing 


switch to the USE16 stack 
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mov cx,ds ; Save entry DS in cx till we get the stack switched 
OV ax,SEG _DATA 
mov ds ,ax 
assume ds:_DATA 
mov ss,word ptr [U16StackAliast+2] 
push ecx ; Entry DS, as DWORD to keep stack aligned 
push ebp 
mov bp,sp 


Frame now looks like this: 


dword ptr [bp + 16] --> Drive # argument (@ = default, A=1...) 


; dword ptr [bp + 12] --> Return CS 

‘ dword ptr [bp + 8] ==), Return EDP 

: dword ptr [bp + 4] --> Entry DS pushed as DWORD 

; dword ptr [bp + 9] --> Entry EBP 

ArgDrv equ dword ptr [bp+16] 
push esi 
push edi 
push ebx 
push es ; Preserve "flat" ES, FS, GS 
push fs 
push gs 
mov edx,ArgDrv ; Drive # to DL 
mov ah,36h 
int 21h ; Make DOS call 
mMOvsx eax ,ax ; Sign extend AX for error 
cmp ax, Q@FFFFh ; Error? 
je short BadDrv ; Yes, return @FFFFFFFFh 
movzx eax ,ax ; Convert sectors/cluster to 32 bit 
movzx ebx , bx ; Convert Available clusters to 32 bit 
MOVZX @CX,CX ; Convert bytes/sector to 32 bit 
mul eCx ; EAX = sectors/cluster * bytes/sector = 
: bytes/cluster 
mul ebx ; EAX = bytes/cluster * Available clusters = 
: free bytes 
BadDrv: 

pop gs 
pop fs 
pop es 
pop ebx 
pop edi 
pop esi 
pop ebp 
pop ecx ; Entry DS in Cx 


; Switch back to the USE32 stack MAKING SURE TO SET HIGH 16 BITS OF ESP. 


mov ss,CU32DataSel J 
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mOovzx esp,sp 


mov ds,cx 

assume ds:nothing 
db 66h ; USE32 override on far ret so it returns to EIP 
ret (1 * 4) 


U32GetDskFree endp 
_HELPERCODE ends 


end 
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\a. See Escape character 
_ __Acrtused symbol, (vol. 2) 13-5 
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use in dialog control statement, (vol. 2) 8-21 to 8-25, 
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BACKSPACE key, (vol. 2) 8-36 
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A (caret), (vol. 2) 8-7, 8-8 
?CHKSTK, Cmacro, (vol. 2) 13-6 
CONTROL key, (vol. 2) 8-8 
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(vol. 2) x 
#define directive, resource compiler, (vol. 2) 8-48 
[[ I (double brackets), as document convention, (vol. 1) 
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#endif directive, resource compiler, (vol. 2) 8-51 
#if directive, resource compiler, (vol. 2) 8-49 to 8-50 
#ifdef directive, resource compiler, (vol. 2) 8-48 
#ifndef directive, resource compiler, (vol. 2) 8-49 
#include directive, resource compiler, (vol. 2) 8-47 
Italic text, as document convention, (vol. 1) xxiv, (vol. 2) 
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_Iclose function, (vol. 1) 3-14, 4-271 
_Icreat function, (vol. 1) 3-14, 4-271 
_llseek function, (vol. 1) 3-14, 4-274 
_lopen function, (vol. 1) 3-14, 4-294 to 4-295 
_lread function, (vol. 1) 3-14, 4-297 
_lwrite function, (vol. 1) 3-14, 4-300 to 4-301 
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xxiv, (vol. 2) ix 
() (parentheses), as document convention, (vol. 1) xxiv, 
(vol. 2) ix 
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calling convention, defined, (vol. 2) 13-8 

Cmacro, (vol. 2) 13-3 to 13-4 
“* (quotation marks), as document convention, (vol. 1) 
xxv, (vol. 2) x 
SHIFT key, (vol. 2) 8-8 
\t. See Escape character 
TAB key, (vol. 2) 8-17 
#undef directive, resource compiler, (vol. 2) 8-48 
| (vertical bar), as document convention, (vol. 1) xxv, 
(vol. 2) x 


2WIN option, Cmacro, (vol. 2) 13-4 
32-bit memory management, (vol. 2) E-1 to E-8 


A 


ABORTDOC printer escape, (vol. 2) 12-2 
Absolute symbol, Cmacro, (vol. 2) 13-5 
Accelerators 

See also ACCELERATORS resource statement 

loading or translating, (vol. 1) 1-4 

with dialog boxes, (vol. 1) 1-52 
ACCELERATORS resource statement, (vol. 2) 8-7 
AccessResource function, (vol. 1) 3-7, 4-2 
AddAtom function, (vol. 1) 3-9, 4-2 
AddFontResource function, (vol. 1) 2-28, 4-3 
Addition (+) operator, (vol. 2) 8-21 to 8-26, 8-28 to 8-33 
AdjustWindowRect function, (vol. 1) 1-7, 4-3 
AdjustWindowRectEx function, (vol. 1) 1-7, 4-4 
Aligning brushes, (vol. 1) 1-39 
Alignment, segment, (vol. 2) 14-5 
AllocDStoCSAlias function, (vol. 1) 3-5, 4-5 
AllocResource function, (vol. 1) 3-7, 4-5 
AllocSelector function, (vol. 1) 3-5, 4-6 
ALTERNATE filling mode, (vol. 1) 4-58, 4-389 
ALTERNATE polygon-filling mode, (vol. 1) 4-58, 
4-197, 4-389 
Ampersand (&), adding a mnemonic with, (vol. 2) 8-10, 
8-21 to 8-25, 8-27 to 8-29 
AnimatePalette function, (vol. 1) 2-10, 4-7 
ANSI table, (vol. 2) D-2 
ANSI_FIXED_FONT stock object, (vol. 1) 4-207 
ANSI_VAR_FONT stock object, (vol. 1) 4-207 
AnsiLower function, (vol. 1) 3-8, 4-7 
AnsiLowerBuff function, (vol. 1) 3-8, 4-8 
AnsiNext function, (vol. 1) 3-8, 4-8 
AnsiPrev function, (vol. 1) 3-8, 4-9 
AnsiToOem function, (vol. 1) 3-8, 4-9 
AnsiToOemBuff function, (vol. 1) 3-8, 4-10 
AnsiUpper function, (vol. 1) 3-8, 4-10 
AnsiUpperBuff function, (vol. 1) 3-8, 4-11 
AnyPopup function, (vol. 1) 1-57, 4-11 
AppendMenu function, (vol. 1) 1-26, 1-56, 4-11 to 4-13, 
4-54, 4-59, 4-211, 6-106 
Application, assembly language, (vol. 2) 13-1 
Arc function, (vol. 1) 2-22, 4-14 
Arg macro 

arguments, position of, (vol. 2) 14-3 

cCall, use with, (vol. 2) 14-2 

Cmacro, (vol. 2) 14-2 


2 Reference 


Argument, cCall list specification, (vol. 2) 14-3 
Argument, macro. See Argument, cCall list specification 
ArrangeIconicWindows function, (vol. 1) 1-28, 4-15 
ASCII character, use with ACCELERATORS statement, 
(vol. 2) 8-7 
ASPECTX device capability, (vol. 1) 4-167 
ASPECTXY device capability, (vol. 1) 4-167 
ASPECTY device capability, (vol. 1) 4-167 
Assembly language 

calling conventions, (vol. 2) 13-3 

checking the stack, (vol. 2) 13-5 

creating, (vol. 2) 13-1 to 13-2 

creating application entry point, (vol. 2) 13-5 

declaring callback functions, (vol. 2) 13-5 

enabling stack checking, (vol. 2) 13-6 

error macros, (vol. 2) 13-9 

macros, (vol. 2) 13-1 

memory options, specifying, (vol. 2) 13-2 

prolog/epilog option, enabling, (vol. 2) 13-4 

segment macros, (vol. 2) 13-6 to 13-7 

special definition macros, (vol. 2) 13-8 

storage-allocation macros, (vol. 2) 13-7 
Assembly-language macro, Cmacro, (vol. 2) 13-6, 14-1 
assumes macro, Cmacro, (vol. 2) 14-2, 14-6 


B 


Background 
brush, class background, (vol. 1) 1-13 
color, default, (vol. 1) 1-33 
mode, default, (vol. 1) 1-33 
BANDINFO printer escape, (vol. 2) 12-2 to 12-4 
BEGIN_PATH printer escape, (vol. 2) 12-5 
BeginDeferWindowPos function, (vol. 1) 1-28, 4-16 
BeginPaint function, (vol. 1) 1-31, 4-16 
BITBLT, example Cmacros function, (vol. 2) 13-9 to 
13-10 
BitBlt function 
and color palettes, (vol. 1) 2-13 
described, (vol. 1) 2-25, 4-17 to 4-19 
Bitmap 
file format, (vol. 2) 7-10 
memory, setting bits in, (vol. 1) 4-375 
mouse cursor shape, (vol. 2) 8-2 
resource, (vol. 2) 8-2 
BITMAP data structure, (vol. 2) 7-6 
Bitmap, device-dependent, getting device-independent 
bits from, (vol. 1) 4-171 
Bitmap, device-independent 
BITMAPCOREHEADER data structure, (vol. 2) 7-8 
BITMAPCOREINFO data structure, (vol. 2) 7-9 
BITMAPINEFO data structure, (vol. 2) 7-11 
BITMAPINFOHEADER data structure, (vol. 2) 7-14 


color, (vol. 2) 7-58 to 7-59 

creating, (vol. 1) 4-44 

described, (vol. 2) 7-9, 7-11 to 7-12 

displaying, (vol. 1) 4-377 

file format, (vol. 2) 9-1 

retrieving bits, (vol. 1) 4-171 

setting on display surface, (vol. 1) 4-377 
Bitmap functions 

device independent, list of, (vol. 1) 2-26 to 2-27 

list of, (vol. 2) 2-25 to 2-26 
BITMAP resource-compiler key word, (vol. 2) 8-2 
BITMAPCOREHEADER data structure, (vol. 2) 7-7, 7-9 
BITMAPCOREINFO 

See also RGBTRIPLE 

data structure, (vol. 2) 7-8 to 7-9 
BITMAPFILEHEADER data structure, (vol. 2) 7-10 
BITMAPINFO 

See also RGBQUAD 

data structure, (vol. 1) 4-45, 4-171, 4-376, (vol. 2) 7-10 to 
7-11, 7-14 
BITMAPINFOHEADER data structure, (vol. 1) 4-44 to 
4-45, (vol. 2) 7-11 to 7-15 
BITSPIXEL device capability, (vol. 1) 4-167 
BLACK_BRUSH stock object, (vol. 1) 4-207 
BLACK_PEN stock object, (vol. 1) 4-207 
BLACKNESS raster-operation code, (vol. 1) 4-19 
BLACKONWHITE stretching mode, (vol. 1) 4-399 
BM_GETCHECK message, (vol. 1) 5-9, 6-4 
BM_GETSTATE message, (vol. 1) 5-9, 6-4 
BM_SETCHECK message, (vol. 1) 5-9, 6-4 
BM_SETSTATE message, (vol. 1) 5-9, 6-5 
BM_SETSTYLE message, (vol. 1) 5-9, 6-5 to 6-6 
BN_CLICKED message, (vol. 1) 5-15, 6-7 
BN_DOUBLECLICKED message, (vol. 1) 5-15, 6-7 
BOOL data type, (vol. 2) 7-1 
Border, window, (vol. 2) 8-16 
Braces, curly ({ }), as document convention, (vol. 1) xxv, 
(vol. 2) x 
Brackets, angle (<>), (vol. 2) 14-5 
Brackets, double ([ ]]), as document convention, (vol. 1) 
Xxv, (vol. 2) x 
BringWindowToTop function, (vol. 1) 1-28, 4-20 
Brush 

alignment, (vol. 1) 1-39 

creating, (vol. 1) 4-35, (vol. 2) 7-39 

default, (vol. 1) 1-33 

origin, default, (vol. 1) 1-33 
BS_3STATE control style, (vol. 1) 4-69, 6-6, (vol. 2) 8-38 
BS_AUTO3STATE control style, (vol. 1) 4-68, 6-6, (vol. 
2) 8-38 
BS_AUTOCHECKBOxX control style, (vol. 1) 4-68, 6-6, 
(vol. 2) 8-37 
BS_AUTORADIOBUTTON control style, (vol. 1) 6-6, 
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(vol. 2) 8-37 
BS_CHECKBOxX control style, (vol. 1) 4-68, 6-6, (vol. 
2) 8-37 
BS_DEFPUSHBUTTON control style, (vol. 1) 4-68, 6-6, 
(vol. 2) 8-37 
BS_GROUPBOxX control style, (vol. 1) 4-68, 6-6, (vol. 
2) 8-38 
BS_HATCHED brush style, (vol. 2) 7-39 
BS_HOLLOW brush style, (vol. 2) 7-39 
BS_LEFTTEXT control style, (vol. 1) 4-68, 6-6, (vol. 2) 
8-37 
BS_OWNERDRAW control style, (vol. 1) 4-69, 6-6 to 
6-7, (vol. 2) 8-38 
BS_PATTERN brush style, (vol. 2) 7-39 
BS_PUSHBUTTON control style, (vol. 1) 4-69, 6-6, 
(vol. 2) 8-37 
BS_RADIOBUTTON control style, (vol. 1) 4-69, 6-6 to 
6-7, (vol. 2) 8-37 
BS_SOLID brush style, (vol. 2) 7-39 
BuildCommDCB function, (vol. 1) 3-11, 4-20 
BUTTON control class 

control styles, (vol. 2) 8-24, 8-27, 8-29 to 8-30, 8-37 

described, (vol. 1) 4-64, 4-68, (vol. 2) 8-23, 8-25, 8-27, 
8-35 
Button notification codes, (vol. 1) 5-15 
Button, owner-draw, (vol. 1) 1-50, (vol. 2) 7-36, 7-48 
BYTE data type, (vol. 2) 7-1 
BYTE, segment alignment type, (vol. 2) 14-5 


C 


C language, library, (vol. 2) 13-5 
Cache, display-context, (vol. 1) 1-36 
Call macros, Cmacro, (vol. 2) 13-8 
Callback functions, (vol. 2) 13-5 
Calling convention 
Cmacro, (vol. 2) 13-3 
high-level language, (vol. 2) 13-3 
Pascal, (vol. 2) 13-3 
CallMsgFilter function, (vol. 1) 1-63, 4-21 
CallWindowProc function, (vol. 1) 1-2, 1-16, 4-21 
Capital letters, small, as document convention, (vol. 1) 
xxv, (vol. 2) x 
CAPTION resource statement, (vol. 2) 8-18 
Caret (4) 
creating and displaying, (vol. 1) 1-61 
functions, (vol. 1) 1-60 
in ACCELERATORS statement, (vol. 2) 8-7 to 8-8 
sharing, (vol. 1) 1-61 
Carriage-return character, (vol. 2) 8-40 
Catch function, (vol. 1) 3-6, 4-22 
CB_ADDSTRING message, (vol. 1) 5-13, 6-8, 6-10 to 
6-11, 6-14, (vol. 2) 7-38, 7-49 


CB_DELETESTRING message, (vol. 1) 5-13, 6-8, 6-57 
CB_DIR message, (vol. 1) 5-13, 6-9 
CB_FINDSTRING message , (vol. 1) 5-13, 6-9 
CB_GETCOUNT message, (vol. 1) 5-14, 6-10 
CB_GETCURSEL message, (vol. 1) 5-14, 6-10 
CB_GETEDITSEL message, (vol. 1) 5-14, 6-10 
CB_GETITEMDATA message, (vol. 1) 5-14, 6-11 
CB_GETLBTEXT message, (vol. 1) 5-14, 6-11 
CB_GETLBTEXTLEN message, (vol. 1) 5-14, 6-12 
CB_INSERTSTRING message, (vol. 1) 5-14, 6-8, 6-10 
to 6-12, 6-14, (vol. 2) 7-38, 7-49 
CB_LIMITTEXT message, (vol. 1) 5-14, 6-12 
CB_RESETCONTENT message, (vol. 1) 5-14, 6-13, 6-57 
CB_SELECTSTRING message, (vol. 1) 5-14, 6-13 
CB_SETCURSEL message, (vol. 1) 5-14, 6-14 
CB_SETEDITSEL message, (vol. 1) 5-14, 6-14 
CB_SETITEMDATA message, (vol. 1) 5-14, 6-11, 6-15 
CB_SHOWDROPDOWN message, (vol. 1) 5-14, 6-15 
cBegin macro, Cmacro, (vol. 2) 14-2 
CBN_DBLCLK message, (vol. 1) 5-17, 6-15 
CBN_DROPDOWN message, (vol. 1) 5-17, 6-16 
CBN_EDITCHANGE message, (vol. 1) 5-17, 6-16 
CBN_EDITUPDATE message, (vol. 1) 5-17, 6-16 
CBN_ERRSPACE message, (vol. 1) 5-17, 6-17 
CBN_KILLFOCUS message, (vol. 1) 5-17, 6-17 
CBN_SELCHANGE message, (vol. 1) 5-17, 6-17 
CBN_SETFOCUS message, (vol. 1) 5-17, 6-18 
CBS_AUTOHSCROLL control style, (vol. 2) 8-39 
CBS_DROPDOWN control style, (vol. 2) 8-38 
CBS_DROPDOWNLIST control style, (vol. 2) 8-38 
CBS_HASSTRINGS control style, (vol. 1) 4-69, 6-8, 
6-10 to 6-12, 6-14, (vol. 2) 8-39 
CBS_OEMCONVERT control style, (vol. 1) 4-70, (vol. 
2) 8-39 
CBS_OWNERDRAWEFIXED control style, (vol. 1) 4-70, 
(vol. 2) 8-38 
CBS_OWNERDRAWVARIABLE control style, (vol. 1) 
4-70, (vol. 2) 8-38 
CBS_SIMPLE control style, (vol. 2) 8-38 
CBS_SORT control style, (vol. 2) 8-39 
cCall macro 

Arg macro, use with, (vol. 2) 14-2 

Cmacro, (vol. 2) 13-8 

FarPtr macro, use with, (vol. 2) 14-9 

Save macro, use with, (vol. 2) 14-14 
CE_BREAK communication error code, (vol. 1) 4-161 
CE_CTSTO communication error code, (vol. 1) 4-161 
CE_DNS communication error code, (vol. 1) 4-161 
CE_DSRTO communication error code, (vol. 1) 4-161 
CE_FRAME communication error code, (vol. 1) 4-161 
CE_IOE communication error code, (vol. 1) 4-161 
CE_MODE communication error code, (vol. 1) 4-161 
CE_OOP communication error code, (vol. 1) 4-161 
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CE_OVERRUN communication error code, (vol. 1) described, (vol. 1) 1-23 

4-161 ChildWindowFromPoint function, (vol. 1) 1-57, 2-20, 
CE_PTO communication error code, (vol. 1) 4-161 4-26 

CE_RLSDTO communication error code, (vol. 1) 4-161 ?CHKSTK, Cmacro, (vol. 2) 13-6 

CE_RXOVER communication error code, (vol. 1) 4-162 Chord function, (vol. 1) 2-24 to 2-25, 4-27 


CE_RXPARITY communication error code, (vol. 1) Class 


4-162 
CE_TXFULL communication error code, (vol. 1) 4-162 
cEnd macro, Cmacro, (vol. 2) 14-3 
CF_BITMAP clipboard format , (vol. 1) 4-370 
CF_DIB clipboard format, (vol. 1) 4-370 
CF_DIF clipboard format, (vol. 1) 4-370 
CF_DSPBITMAP clipboard format, (vol. 1) 4-370 
CF_DSPMETAFILEPICT clipboard format, (vol. 1) 
4-370 
CF_DSPTEXT clipboard format, (vol. 1) 4-370 
CF_METAFILEPICT clipboard format, (vol. 1) 4-370 
CF_OEMTEXT clipboard format, (vol. 1) 4-371 
CF_OWNERDISPLAY clipboard format, (vol. 1) 4-371 
CF_PALETTE clipboard format, (vol. 1) 4-157, 4-371 
CF_SYLK clipboard format, (vol. 1) 4-371 
CF_TEXT clipboard format, (vol. 1) 4-371 
CF_TIFF clipboard format, (vol. 1) 4-371 
ChangeClipboardChain function, (vol. 1) 1-59, 4-23 
ChangeMenu. See AppendMenu; DeleteMenu; 
InsertMenu; ModifyMenu; RemoveMenu 
ChangeMenu function, (vol. 1) 4-23 
ChangeSelector function, (vol. 1) 3-5, 4-24 
char data type, (vol. 2) 7-1 
Character 

determining if alphabetic, (vol. 1) 4-263 

determining if alphanumeric, (vol. 1) 4-264 

determining if lowercase, (vol. 1) 4-264 

determining if uppercase, (vol. 1) 4-264 

escape 

\a, (vol. 2) 8-10 
\t, (vol. 2) 8-10 

Character cell, (vol. 1) 2-31 
Character tables, (vol. 2) D-1 to D-2 
CHECKBOX resource statement 

described, (vol. 2) 8-23 to 8-24 

DIALOG resource statement, (vol. 2) 8-20 
CheckDlgButton function, (vol. 1) 1-43, 4-24 
CHECKED option 

MENUITEM resource statement, (vol. 2) 8-10 

POPUP resource statement, (vol. 2) 8-12 
Checkmark 


Application Global, (vol. 1) 1-9 
Application Local, (vol. 1) 1-9 
class background brush 
assigning, (vol. 1) 1-13 
setting, (vol. 1) 1-13 
class name 
assigning, (vol. 1) 1-11 
global uniqueness, (vol. 1) 1-11 
creating, (vol. 1) 1-8 
Cursor, (vol. 1) 1-12 
defining and registering, (vol. 1) 1-8 
determining ownership, (vol. 1) 1-9 
display contexts, (vol. 1) 1-18 
elements, (vol. 1) 1-10 
assigning, (vol. 1) 1-10 
class names, (vol. 1) 1-10 
instance handle, (vol. 1) 1-12 
functions 
default messages, (vol. 1) 1-20 
defining, (vol. 1) 1-18, 1-20 
examining, (vol. 1) 1-18, 1-20 
receiving, (vol. 1) 1-18, 1-20 
responding, (vol. 1) 1-18, 1-20 
icon, (vol. 1) 1-12 
menu, (vol. 1) 1-14 
messages 
declaring, (vol. 1) 1-20 
sending, (vol. 1) 1-20 
values, (vol. 1) 1-20 
predefined, (vol. 1) 1-10 
redrawing client area, (vol. 1) 1-17 
registering, (vol. 1) 1-9, 1-20 
shared, (vol. 1) 1-10 
styles 
child, (vol. 1) 1-23 
described, (vol. 1) 1-14 to 1-15 
overlapped, (vol. 1) 1-22 
owned, (vol. 1) 1-22 
pop-up, (vol. 1) 1-23 
System Global, (vol. 1) 1-8 


window, unregistering, (vol. 1) 4-452 
CLASS resource statement, (vol. 2) 8-19 
ClearCommBreak function, (vol. 1) 3-11, 4-28 
Client area 

child window, (vol. 1) 1-23 

painting, (vol. 2) 7-55 

redrawing, (vol. 1) 1-17 


custom, (vol. 1) 4-385 

getting size of, (vol. 1) 4-184 
CheckMenultem function, (vol. 1) 1-56, 4-25, 4-311 
CheckRadioButton function, (vol. 1) 1-43, 4-26 
Child window 

clipping, (vol. 2) 8-16 
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update region, (vol. 1) 1-38 
CLIENTCREATESTRUCT data structure, (vol. 1) 1-25, 
5-19, (vol. 2) 7-16 
ClientToScreen function, (vol. 1) 2-20, 4-28 
CLIP_TO_PATH printer escape, (vol. 2) 12-6 
Clipboard 

file format, (vol. 2) 9-5 

formats, (vol. 1) 4-370 

functions, (vol. 1) 1-58 

getting prioritized format, (vol. 1) 4-197 
CLIPCAPS device capability, (vol. 1) 4-167 
ClipCursor function, (vol. 1) 1-62, 4-29 
Clipping, child window, (vol. 2) 8-16 
Clipping functions, (vol. 1) 2-22 to 2-23 
Clipping region, default, (vol. 1) 1-33 
CloseClipboard function, (vol. 1) 1-59, 4-29 
CloseComm function, (vol. 1) 3-11, 4-29 
CloseMetaFile function, (vol. 1) 2-41, 4-30 
CloseSound function, (vol. 1) 3-12, 4-30 
CloseWindow function, (vol. 1) 1-28, 4-30 
CLRDTR communication function code, (vol. 1) 4-128 
CLRRTS communication function code, (vol. 1) 4-128 
Cmacro 

Arg macro, arguments, position of, (vol. 2) 14-2 to 14-3 

assumes macro, (vol. 2) 14-2 

BITBLT sample function, (vol. 2) 13-9 

call macros, (vol. 2) 13-8 

calling convention, (vol. 2) 13-3 

calling cProc function, (vol. 2) 13-8 

calling high-level-language function, (vol. 2) 13-8 

cBegin macro, (vol. 2) 14-2 

cCall macro, (vol. 2) 13-8 

cEnd macro, (vol. 2) 14-3 

codeOFFSET macro, (vol. 2) 14-4 

cProc macro, (vol. 2) 13-8 

createSeg macro, (vol. 2) 14-6 

dataOFFSET macro, (vol. 2) 14-6 

defined, (vol. 2) 13-6, 14-1 

DefX macro, (vol. 2) 14-7 

erm$ macro, (vol. 2) 14-7 

errnz macro, (vol. 2) 14-8 

Error macros, (vol. 2) 13-9 

example, (vol. 2) 13-9, 13-10 

externX macro, (vol. 2) 14-9 

FarPtr macro, (vol. 2) 14-9 

function, (vol. 2) 13-8 

globalX macro, (vol. 2) 14-10 

INCLUDE directive, (vol. 2) 13-4 

labelX macro, (vol. 2) 14-11 

localX macro, (vol. 2) 13-9, 14-11 

memory-model options, (vol. 2) 13-2 

options, (vol. 2) 13-1 

overriding type, (vol. 2) 13-9 


parmX macro, (vol. 2) 13-9 to 13-10, 14-5 
?PLM option, (vol. 2) 13-4, 13-8 
Save macro, (vol. 2) 14-14 
sBegin macro, (vol. 2) 14-14 
segment macros 
CODE segment, (vol. 2) 14-6 
DATA segment, (vol. 2) 14-6 
described, (vol. 2) 13-6 
segNameOFFSET macro, (vol. 2) 14-14 
sEnd macro, (vol. 2) 14-15 
special-definitions macros, (vol. 2) 13-8 
stack-checking option, (vol. 2) 13-6 
staticX macro, (vol. 2) 14-15 
storage-allocation macros, (vol. 2) 13-7 
symbol redefinition, (vol. 2) 13-10 
2WIN option, (vol. 2) 13-4 
Windows prolog/epilog, (vol. 2) 13-4 
CMACROS.INC file, (vol. 2) 13-4 
CODE module-definition statement, (vol. 2) 10-2 
Code segment attributes, defining, (vol. 2) 10-2, 10-8 
CODE segment, Cmacro, (vol. 2) 14-6 
CODE statement, (vol. 2) 10-1 
codeOFFSET macro, Cmacro, (vol. 2) 14-4 
Coding instruction sequences, (vol. 2) 13-9 
Color 
data types, (vol. 2) 7-17 
explicit RGB, (vol. 2) 7-17 
logical-palette index, (vol. 1) 4-327, (vol. 2) 7-17 
palette-relative RGB, (vol. 2) 7-17 
specifying, (vol. 2) 7-17 
using color in logical palette, (vol. 1) 4-327 to 4-328 
COLOR_ACTIVEBORDER system color, (vol. 1) 4-401 
COLOR_ACTIVECAPTION system color, (vol. 1) 1-13, 
4-401 
COLOR_APPWORKSPACE system color, (vol. 1) 1-13, 
4-401 
COLOR_BACKGROUND system color, (vol. 1) 1-13, 
4-401 
COLOR_BTNFACE system color, (vol. 1) 1-13, 4-401 
COLOR_BTNSHADOW system color, (vol. 1) 1-13, 
4-401 
COLOR_BTNTEXT system color, (vol. 1) 4-401 
COLOR_CAPTIONTEXT system color, (vol. 1) 1-13, 
4-401 
COLOR_GRAYTEXT system color, (vol. 1) 1-13, 
4-250, 4-401 
COLOR_HIGHLIGHT systeni color, (vol. 1) 1-13, 4-401 
COLOR_HIGHLIGHTTEXT system color, (vol. 1) 1-13, 
4-401 
COLOR_INACTIVEBORDER system color, (vol. 1) 
4-401 
COLOR_INACTIVECAPTION system color, (vol. 1) 
1-13, 4-401 
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COLOR_MENU system color, (vol. 1) 1-13, 4-401 
COLOR_MENUTEXT system color, (vol. 1) 1-13, 4-401 
Color palette 
See also Logical palette 
default, (vol. 1) 1-33 
updating client area, (vol. 1) 4-452 
COLOR_SCROLLBAR system color, (vol. 1) 1-13, 
4-401 
COLOR_WINDOW system color, (vol. 1) 1-13, 4-401 
COLOR_WINDOWFRAME system color, (vol. 1) 1-13, 
4-401 
COLOR_WINDOWTEXT system color, (vol. 1) 1-13, 
4-401 
COLORONCOLOR stretching mode, (vol. 1) 4-399 
COLORREF data type, (vol. 1) 2-9, 3-13, (vol. 2) 7-17 to 
7-18 
Combine type, segments, (vol. 2) 14-6 
CombineRgn function, (vol. 1) 2-21, 4-31 
Combo box 
deleted item, (vol. 2) 7-26 
described, (vol. 1) 1-50 
owner-draw 
described, (vol. 1) 1-50 to 1-51 
new item position, (vol. 1) 6-53 
sorting, (vol. 2) 7-19 
COMBOBOX control class 
control styles, (vol. 1) 4-69, (vol. 2) 8-32, 8-38 
described, (vol. 1) 4-64, (vol. 2) 8-32, 8-35 
COMBOBOX resource statement 
described, (vol. 2) 8-31 to 8-32 
DIALOG resource statement, (vol. 2) 8-20 
Command, Cmacro 
EQU, (vol. 2) 13-3 
INCLUDE, (vol. 2) 13-4 
COMMON combine type, Cmacro, (vol. 2) 14-6 
Communication devices, (vol. 2) 7-20, 7-22 
COMPAREITEMSTRUCT data structure, (vol. 1) 6-53, 
(vol. 2) 7-19 
COMPLEXREGION region type, (vol. 1) 4-32, 4-129, 
4-158, 4-224, 4-260, 4-318 to 4-319, 4-359 
COMSTAT data structure, (vol. 2) 7-20 
Contexts 
class and private, (vol. 1) 1-18 
classes, displaying, (vol. 1) 1-34 
displaying, (vol. 1) 1-32 
displaying cache, (vol. 1) 1-36 
displaying common defaults, (vol. 1) 1-33 
painting changes, (vol. 1) 1-36 
private display, (vol. 1) 1-35 
window display, (vol. 1) 1-35 
WM_PAINT message, (vol. 1) 1-36 
Control 
current font, (vol. 1) 6-62 


owner-draw See Control, owner-draw 
setting current font, (vol. 1) 6-99 
size-box, (vol. 2) 8-36 
Control class 
BUTTON 
control styles, (vol. 2) 8-37 
described, (vol. 2) 8-35 
COMBOBOX 
control styles, (vol. 1) 4-69 
described, (vol. 1) 4-64, (vol. 2) 8-35 
control styles, described, (vol. 2) 8-37 
described, (vol. 2) 8-35 
EDIT, (vol. 2) 8-36 
EDIT, control styles, (vol. 2) 8-39 
LISTBOX, (vol. 2) 8-36 
LISTBOX control styles, (vol. 2) 8-41 
SCROLLBAR, (vol. 2) 8-36 
SCROLLBAR control styles, (vol. 2) 8-43 
STATIC, (vol. 2) 8-36 
Control, edit See Edit control 
CONTROL option, ACCELERATORS resource 
statement, (vol. 2) 8-8 
Control, owner-draw 
described, (vol. 1) 1-50 
drawing, (vol. 1) 6-58, 6-79, (vol. 2) 7-36 
item deleted from, (vol. 2) 7-27 
measuring, (vol. 1) 6-79 
CONTROL resource statement 
described, (vol. 2) 8-34 to 8-35 
DIALOG resource statement, (vol. 2) 8-20 
Control styles 
BUTTON class, (vol. 2) 8-37 
COMBOBOX class, (vol. 1) 4-69, (vol. 2) 8-38 
described, (vol. 2) 8-37 
EDIT class, (vol. 2) 8-39 
LISTBOX< class, (vol. 2) 8-41 
SCROLLBAR class, (vol. 2) 8-43 
Control text 
centered, (vol. 2) 8-22 
left-justified, (vol. 2) 8-20 
right-justified, (vol. 2) 8-21 
Control window, user-defined, (vol. 2) 8-34 
Coordinate functions, (vol. 1) 2-20 
CopyMetaFile function, (vol. 1) 2-41, 4-32 
CopyRect function, (vol. 1) 1-67, 4-32 
CountClipboardFormats function, (vol. 1) 4-33 
CountVoiceNotes function, (vol. 1) 3-12, 4-33 
cProc macro, Cmacro, (vol. 2) 13-8 
CreateBitmap function, (vol. 1) 2-25, 4-33 
CreateBitmapIndirect function, (vol. 1) 2-25, 4-34 
CreateBrushIndirect function, (vol. 1) 2-5, 4-35 
CreateCaret function, (vol. 1) 1-60, 4-35 
CreateCompatibleBitmap function, (vol. 1) 2-25, 4-36 
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CreateCompatibleDC function, (vol. 1) 2-2, 4-37 
CreateCursor function, (vol. 1) 1-62, 4-38 
CreateDC function, (vol. 1) 2-2, 4-38 
CreateDialog function, (vol. 1) 1-43, 1-46, 4-39 to 4-40, 
4-44, 4-78 
CreateDialogIndirect function, (vol. 1) 1-43, 4-41 to 
4-42, 4-78, 6-100 
CreateDialogIndirectParam function, (vol. 1) 1-43, 4-43, 
4-79, 6-100 
CreateDialogParam function, (vol. 1) 1-43, 4-44, 4-79 
CreateDIBitmap function, (vol. 1) 2-26, 4-44 to 4-45 
CreateDIBPatternBrush function, (vol. 1) 2-5, 4-46 
CreateDiscardableBitmap function, (vol. 1) 2-25, 4-46 
CreateEllipticRgn function, (vol. 1) 2-21, 4-47 
CreateEllipticRgnIndirect function, (vol. 1) 2-21, 4-48 
CreateFont function, (vol. 1) 2-28, 4-48 to 4-50 
CreateFontIndirect function, (vol. 1) 2-28, 4-51 
CreateHatchBrush function, (vol. 1) 2-5, 4-51 
CreateIC function, (vol. 1) 2-2, 4-52 
CreateIcon function, (vol. 1) 1-39, 4-53 
CreateMenu function, (vol. 1) 1-56, 4-54 
CreateMetaFile function, (vol. 1) 2-41, 4-54 
CreatePalette function, (vol. 1) 2-10, 4-7, 4-55, 4-361 
CreatePatternBrush function, (vol. 1) 2-6, 4-55 
CreatePen function, (vol. 1) 2-6, 4-56 
CreatePenIndirect function, (vol. 1) 2-6, 4-57 
CreatePolygonRgn function, (vol. 1) 2-21, 4-57 
CreatePolyPolygonRgn function, (vol. 1) 2-21, 4-58 
CreatePopupMenu function, (vol. 1) 1-26, 1-56, 4-59 
CreateRectRgn function, (vol. 1) 2-21, 4-59 
CreateRectRgnIndirect function, (vol. 1) 2-21, 4-60 
CreateRoundRectRgn function, (vol. 1) 2-21, 4-60 
createSeg macro, Cmacro, (vol. 2) 14-6 
CreateSolidBrush function, (vol. 1) 2-6, 4-61 
CREATESTRUCT data structure, (vol. 2) 7-21 
CreateWindow function, (vol. 1) 1-3 

creating a child window, (vol. 1) 1-23 

creating a window with dialog-box attributes, (vol. 2) 
8-15 

creating an overlapped window, (vol. 1) 1-22 

described, (vol. 1) 1-7, 4-61 to 4-75 
CreateWindowEx function, (vol. 1) 1-7, 4-4, 4-76 to 4-77 
Creating windows, (vol. 2) 8-15 
CS_BYTEALIGNCLIENT window class style, (vol. 1) 
1-14, (vol. 2) 7-62 
CS_BYTEALIGNWINDOW window class style, (vol. 1) 
1-14, (vol. 2) 7-62 
CS_CLASSDC window class style, (vol. 1) 1-14, 1-34, 
(vol. 2) 7-62 
CS_DBLCLKS window class style, (vol. 1) 1-14, (vol. 2) 
7-62 
CS_GLOBALCLASS window class style, (vol. 1) 1-15 
CS_HREDRAW window class style, (vol. 1) 1-15, (vol. 


2) 7-63 
CS_NOCLOSE window class style, (vol. 1) 1-15, (vol. 2) 
7-63 
CS_OWNDC window class style, (vol. 1) 1-15, 1-17, 
1-35, (vol. 2) 7-63 
CS_PARENTDC window class style, (vol. 1) 1-15, (vol. 
2) 7-63 
CS_SAVEBITS window class style, (vol. 1) 1-15, (vol. 
2) 7-64 
CS_VREDRAW window class style, (vol. 1) 1-15, (vol. 
2) 7-64 
CTEXT resource statement, (vol. 2) 8-22 to 8-23 
CTLCOLOR_BTN control type for setting color, (vol. 1) 
6-54 
CTLCOLOR_DLG control type for setting color, (vol. 1) 
6-54 
CTLCOLOR_EDIT control type for setting color, (vol. 1) 
6-55 
CTLCOLOR_LISTBOX control type for setting color, 
(vol. 1) 6-55 
CTLCOLOR_MSGBOxX control type for setting color, 
(vol. 1) 6-55 
CTLCOLOR_SCROLLBAR control type for setting 
color, (vol. 1) 6-55 
CTLCOLOR_STATIC control type for setting color, 
(vol. 1) 6-55 
Curly braces ({ }), as document convention, (vol. 1) xxv, 
(vol. 2) x 
Cursor 

class, (vol. 1) 1-12 

confining, (vol. 1) 1-63 

creating custom, (vol. 1) 1-63 

displaying and hiding, (vol. 1) 1-62 

file format, (vol. 2) 9-3 

functions, (vol. 1) 1-61 

positioning, (vol. 1) 1-63 

resource, (vol. 2) 8-2 

with pointing devices, (vol. 1) 1-62 
CURSOR resource-compiler key word, (vol. 2) 8-2 
CURVECAPS device capability, (vol. 1) 4-168 
CW_USEDEFAULT default window width, (vol. 2) 7-47 


D 


DATA module-definition statement, (vol. 2) 10-2 
Data object, 32-bit, (vol. 2) E-7 

Data segment attributes, defining, (vol. 2) 10-2, 10-8 
DATA segment, Cmacro, (vol. 2) 14-6 

DATA statement, (vol. 2) 10-1 

Data types, naming conventions, (vol. 2) 7-1, 7-5 
dataOFFSET macro, Cmacro, (vol. 2) 14-6 
DC_BINS device capability, (vol. 1) 4-91 
DC_DRIVER device capability, (vol. 1) 4-92 
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DC_DUPLEX device capability, (vol. 1) 4-92 DEVICE_DEFAULT_FONT stock object, (vol. 1) 4-207 
DC_EXTRA device capability, (vol. 1) 4-92 Device driver, device capabilities, (vol. 1) 4-91 
DC_FIELDS device capability, (vol. 1) 4-92 Device-independent bitmap. See Bitmap, 
DC_MAXEXTENT device capability, (vol. 1) 4-92 device-independent 
DC_MINEXTENT device capability, (vol. 1) 4-92 DeviceCapabilities function, (vol. 1) 2-44, 4-91 to 4-93 
DC_PAPERS device capability, (vol. 1) 4-93 DEVICEDATA printer escape, (vol. 2) 12-7. See 
DC_PAPERSIZE device capability, (vol. 1) 4-93 PASSTHROUGH printer escape 
DC_SIZE device capability, (vol. 1) 4-93 DeviceMode function, (vol. 1) 2-44, 4-94 
DC_VERSION device capability, (vol. 1) 4-93 Devices, communication, (vol. 2) 7-20, 7-22 
DCB data structure, (vol. 2) 7-22 to 7-25 DEVMODE data structure, (vol. 1) 4-92 to 4-93, 4-131, 
DDE (vol. 2) 7-27 to 7-30 
messages, (vol. 2) 15-1 Dialog box 
protocol, (vol. 2) 15-1 accelerators, (vol. 1) 1-52 
DebugBreak function, (vol. 1) 3-14, 4-78 buttons, (vol. 1) 1-49 
.DEF file. See Module-definition file control identifiers, (vol. 1) 1-48 
DEFAULT_PALETTE stock object, (vol. 1) 4-208 control styles, (vol. 1) 1-48 
Default pushbutton control, (vol. 2) 8-28 controls 
DefDlgProc function, (vol. 1) 1-7, 1-43, 4-78, (vol. 2) control messages, (vol. 1) 1-51 
8-19 described, (vol. 1) 1-47, 1-51 
DeferWindowPos function, (vol. 1) 1-28, 4-79 to 4-80 creating, (vol. 1) 1-45 to 1-46, (vol. 2) 7-31, 8-13 
DefFrameProc function, (vol. 1) 1-7, 4-81 described, (vol. 1) 1-43 
DefHookProc function, (vol. 1) 1-63, 4-82 dimensions, (vol. 1) 1-51 
#define directive, resource compiler, (vol. 2) 8-48 edit controls, (vol. 1) 1-49 
DefineHandleTable function, (vol. 1) 3-3, 3-5, 4-83 input function, (vol. 1) 1-46 
DefMDIChildProc function, (vol. 1) 1-7, 4-84 items, (vol. 2) 7-34 
DEFPUSHBUTTON resource statement keyboard input, (vol. 1) 1-52 
described, (vol. 2) 8-28 to 8-29 keyboard interface 
DIALOG resource statement, (vol. 2) 8-20 actions, (vol. 1) 1-51 
DefWindowProc function, (vol. 1) 1-7, 4-85 filtering, measurements, (vol. 1) 1-52 
DefX macro, Cmacro, (vol. 2) 14-7 scrolling, (vol. 1) 1-52 
DeleteAtom function, (vol. 1) 3-9, 4-86 modal 
DeleteDC function, (vol. 1) 2-2, 4-37, 4-86 creating, (vol. 1) 1-46, 4-98 to 4-99 
DELETEITEMSTRUCT data structure moveable, (vol. 1) 1-45 
as parameter of WM_DELETEITEM message, (vol. 1) modeless 
6-57 creating, (vol. 1) 4-43 to 4-44 
described, (vol. 2) 7-26 deleting, (vol. 1) 1-45 
DeleteMenu function, (vol. 1) 1-56, 4-87 using, (vol. 1) 1-45 
DeleteMetaFile function, (vol. 1) 2-41, 4-87 owner draw, (vol. 1) 1-51 
DeleteObject function, (vol. 1) 2-6, 4-88, 6-99 private window class default function, (vol. 1) 4-78 
DESCRIPTION module-definition statement, (vol. 2) redrawing, (vol. 1) 1-51 
10-3 return values, (vol. 1) 1-47 
DESCRIPTION statement, (vol. 2) 10-1 scrolling, (vol. 1) 1-52 
DestroyCaret function, (vol. 1) 1-60, 4-88 template, (vol. 1) 1-46, (vol. 2) 8-13 
DestroyCursor function, (vol. 1) 1-62, 4-89 text font, (vol. 2) 7-34 
DestroyMenu function, (vol. 1) 1-56, 4-90 using, (vol. 1) 1-45 
Destroy Window function window style, (vol. 2) 8-15 
described, (vol. 1) 1-7, 4-90 Dialog box units, (vol. 2) 8-21 to 8-30, 8-32 
destroying modeless dialog boxes, (vol. 1) 1-45 Dialog functions, (vol. 1) 1-43 
effect, (vol. 1) 1-28 Dialog option statements, (vol. 2) 8-15 
Device context DIALOG resource statement 
attributes and functions, (vol. 1) 2-3 control class, control styles, (vol. 2) 8-37 
creating, saving and deleting, (vol. 1) 2-4 described, (vol. 2) 8-13 


functions, described, (vol. 1) 2-2 dialog control statements 


CHECKBOX, (vol. 2) 8-20, 8-23 
COMBOBOXx, (vol. 2) 8-20, 8-31 
CONTROL, (vol. 2) 8-20, 8-34 
control classes, (vol. 2) 8-35 
CTEXT, (vol. 2) 8-20, 8-22 
DEFPUSHBUTTON, (vol. 2) 8-20, 8-28 
EDITTEXT, (vol. 2) 8-20, 8-30 
GROUPBOXx, (vol. 2) 8-20, 8-27 
ICON, (vol. 2) 8-20, 8-33 
LISTBOX, (vol. 2) 8-20, 8-26 
LTEXT, (vol. 2) 8-20 
PUSHBUTTON, (vol. 2) 8-20, 8-25 
RADIOBUTTON, (vol. 2) 8-20, 8-29 
RTEXT, (vol. 2) 8-20 to 8-21 
SCROLLBAR, (vol. 2) 8-33 
dialog option statement 
CAPTION, (vol. 2) 8-15, 8-18 
CLASS, (vol. 2) 8-15, 8-19 
FONT, (vol. 2) 8-15, 8-19 
MENU, (vol. 2) 8-15, 8-18 
STYLE, (vol. 2) 8-14 to 8-15 
DIALOG template, (vol. 2) 8-13 


DialogBox function, (vol. 1) 1-43, 1-46, 4-79, 4-95, (vol. 


2) 8-14 
DialogBoxIndirect function, (vol. 1) 1-43, 4-79, 4-96 to 
4-97, 6-100 
DialogBoxIndirectParam function, (vol. 1) 1-43, 4-79, 
4-98, 6-100 ’ 
DialogBoxParam function, (vol. 1) 1-43, 4-79, 4-99 
DIB. See Bitmap, device-independent 
DIB_PAL_COLORS, device-independent bitmap color 
table option, (vol. 1) 4-45 to 4-46, 4-172, 4-376, 4-378, 
4-436, (vol. 2) 7-9, 7-12, 7-39, 9-15 
DIB_RGB_COLORS, device-independent bitmap color 
table option, (vol. 1) 4-45 to 4-46, 4-172, 4-376, 4-378, 
4-436, (vol. 2) 7-39, 9-15 
Digitized aspect, fonts, (vol. 1) 2-36 
Directive, resource compiler 

#define, (vol. 2) 8-48 

described, (vol. 2) 8-47 

#elif, (vol. 2) 8-50 

#else, (vol. 2) 8-50 

#endif, (vol. 2) 8-51 

#if, (vol. 2) 8-49 

#ifdef, (vol. 2) 8-48 

#ifndef, (vol. 2) 8-49 

#include, (vol. 2) 8-47 

#undef, (vol. 2) 8-48 
Disabled window, (vol. 2) 8-14 
DISCARDABLE resource-compiler key word, (vol. 2) 
8-2, 8-4 to 8-6, 8-9, 8-14 
DispatchMessage function, (vol. 1) 1-2, 4-99 
Display context default characteristics, (vol. 1) 1-33 
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Display, updating, (vol. 1) 1-37 
DKGRAY_BRUSH stock object, (vol. 1) 4-207 
DLGC_DEFPUSHBUTTON input type, (vol. 1) 6-62 
DLGC_HASSETSEL input type, (vol. 1) 6-62 
DLGC_PUSHBUTTON input type, (vol. 1) 6-62 
DLGC_RADIOBUTTON input type, (vol. 1) 6-62 
DLGC_WANTALLKEYS input type, (vol. 1) 6-62 
DLGC_WANTARROWS input type, (vol. 1) 6-62 
DLGC_WANTCHARS input type, (vol. 1) 6-62 
DLGC_WANTMESSAGE input type, (vol. 1) 6-62 
DLGC_WANTTAB input type, (vol. 1) 6-62 
DigDirList function, (vol. 1) 1-43, 4-100 to 4-101 
DlgDirListComboBox function, (vol. 1) 1-43, 4-102 
DlgDirSelect function, (vol. 1) 1-44, 4-103 
DlgDirSelectComboBox function, (vol. 1) 1-44, 4-104 
DLGITEMTEMPLATE data structure, (vol. 2) 7-34 
DLGTEMPLATE 

data structure, (vol. 1) 6-100, (vol. 2) 7-31 to 7-35 

DLGITEMTEMPLATE data structure, (vol. 2) 7-34 

FONTINFO data structure, (vol. 2) 7-34 
DM_COPY option, (vol. 1) 4-131 
DM_GETDEFID message, (vol. 1) 5-9, 6-19 
DM_MODIFY option, (vol. 1) 4-132 
DM_PROMPT option, (vol. 1) 4-132 
DM_SETDEFID message, (vol. 1) 5-9, 6-19 
DM_UPDATE option, (vol. 1) 4-132 
Document conventions 

bold text, (vol. 1) xxiv, (vol. 2) ix 

curly braces ({ }), (vol. 1) xxv, (vol. 2) x 

double brackets ([[ J), (vol. 1) xxv, (vol. 2) x 

horizontal ellipses (. . .), (vol. 1) xxiv, (vol. 2) ix 

monospaced type, (vol. 1) xxiv, (vol. 2) ix 

italic text, (vol. 1) xxiv, (vol. 2) ix 

parentheses ( ), (vol. 1) xxiv, (vol. 2) ix 

quotation marks (“”’), (vol. 1) xxv, (vol. 2) x 

small capital letters, (vol. 1) xxv, (vol. 2) x 

vertical bar (1), (vol. 1) xxv, (vol. 2) x 

vertical ellipses, (vol. 1) xxiv, (vol. 2) ix 
DOS interrupt function request (21H), (vol. 1) 4-104 
DOS3Call function, (vol. 1) 3-6, 4-104 
Double brackets ([[ ]), as document convention, (vol. 1) 
xxv, (vol. 2) x 
Double quotation marks (‘‘’””), (vol. 2) 8-6 to 8-7, 8-10, 
8-19 
DPtoLP function, (vol. 1) 2-20, 4-105 
DRAFT_QUALITY font quality, (vol. 2) 7-43 
DRAFTMODE printer escape, (vol. 2) 12-7 
DrawFocusRect function, (vol. 1) 1-31, 2-24, 4-106 
DrawlIcon function, (vol. 1) 1-31, 4-106 
Drawing 

formatted text, (vol. 1) 1-40 

gray text, (vol. 1) 1-42 

icons, (vol. 1) 1-39 
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mode, default, (vol. 1) 1-33 
DRAWITEMSTRUCT 

as parameter of WM_DRAWITEM message, (vol. 1) 
6-59 

data structure, described, (vol. 2) 7-36 to 7-37 
DrawMenuBar function, (vol. 1) 1-56, 4-12, 4-87, 4-107, 
4-257, 4-311, 4-350 
DRAWPATTERNRECT printer escape, (vol. 2) 12-8 
DrawText function, (vol. 1) 1-31, 4-107 to 4-109 
Driver, printer initialization, (vol. 2) 7-27 
DRIVERVERSION device capability, (vol. 1) 4-167 
Drop-down menu. See Pop-up menu 
DS_ABSALIGN dialog-box style, (vol. 2) 7-32, 8-14 to 
8-15 
DS_LOCALEDIT dialog-box style, (vol. 1) 4-66, (vol. 2) 
7-32, 8-16 
DS_MODALFRAME dialog-box style, (vol. 1) 4-66, 
(vol. 2) 7-32, 8-16 
DS_NOIDLEMSG dialog-box style, (vol. 1) 4-66, (vol. 
2) 7-33, 8-16 
DS_SETFONT dialog-box style, (vol. 1) 6-100, (vol. 2) 
7-32 
DS_SYSMODAL dialog-box style, (vol. 1) 4-66, (vol. 2) 
7-32, 8-16 
DSTINVERT raster operation, (vol. 1) 4-19 
DT_BOTTOM format for DrawText function, (vol. 1) 
4-108 
DT_CALCRECT format for DrawText function, (vol. 1) 
4-108 
DT_EXPANDTABS format for DrawText function, (vol. 
1) 4-108 
DT_EXTERNALLEADING format for DrawText 
function, (vol. 1) 4-108 
DT_NOCLIP format for DrawText function, (vol. 1) 
4-108 
DT_NOPREFIX format for DrawText function, (vol. 1) 
4-109 
DT_SINGLELINE format for DrawText function, (vol. 
1) 4-109 
DT_TABSTOP format for DrawText function, (vol. 1) 
4-109 
DT_TOP format for DrawText function, (vol. 1) 4-109 
DT_VCENTER format for DrawText function, (vol. 1) 
4-109 
DT_WORDBREAK format for DrawText function, (vol. 
1) 4-109 
DUP assembler operator, (vol. 2) 14-15 
DWORD data type, (vol. 2) 7-1 
Dynamic Data Exchange. See DDE 


E 


Edit control 

described, (vol. 2) 8-30 to 8-31, 8-40 

tab stops in, (vol. 1) 6-28 
EDIT control class 

control styles, (vol. 2) 8-31, 8-39 

described, (vol. 1) 4-64, (vol. 2) 8-36 
Edit-control notification codes, (vol. 1) 5-16 
Editing keys, (vol. 2) 8-30 
EDITTEXT resource statement 

described, (vol. 2) 8-30 to 8-31 

style option, (vol. 2) 8-30 
EDITTEXT statement, DIALOG resource statement, 
(vol. 2) 8-20 
#elif directive, resource compiler, (vol. 2) 8-50 
Ellipse function, (vol. 1) 2-24 to 2-25, 4-110 
Ellipses 


horizontal, as document convention, (vol. 1) xxiv, (vol. 2) 


ix 


vertical, as document convention, (vol. 1) xxiv, (vol. 2) ix 


#else directive, resource compiler, (vol. 2) 8-50 
EM_CANUNDO message, (vol. 1) 5-10, 6-20 
EM_EMPTYUNDOBUFFER message, (vol. 1) 5-10, 
6-20 

EM_FMTLINES message, (vol. 1) 5-10, 6-20 
EM_GETHANDLE message, (vol. 1) 5-10, 6-21 
EM_GETLINE message, (vol. 1) 5-10, 6-21 
EM_GETLINECOUNT message, (vol. 1) 5-10, 6-22 
EM_GETMODIFY message, (vol. 1) 5-10, 6-22 
EM_GETRECT message, (vol. 1) 5-10, 6-22 
EM_GETSEL message, (vol. 1) 5-10, 6-23 
EM_LIMITTEXT message, (vol. 1) 5-10, 6-23 
EM_LINEFROMCHAR message, (vol. 1) 5-10, 6-23 
EM_LINEINDEX message, (vol. 1) 5-10, 6-24 
EM_LINELENGTH message, (vol. 1) 5-10, 6-24 
EM_LINESCROLL message, (vol. 1) 5-10, 6-25 
EM_REPLACESEL message, (vol. 1) 5-11, 6-25 
EM_SETHANDLE message, (vol. 1) 5-11, 6-26 
EM_SETMODIFY message, (vol. 1) 5-11, 6-26 
EM_SETPASSWORDCHAR message, (vol. 1) 4-71, 
5-11, 6-26, (vol. 2) 8-40 

EM_SETRECT message, (vol. 1) 5-11, 6-27 
EM_SETRECTNP message, (vol. 1) 5-11, 6-27 
EM_SETSEL message, (vol. 1) 5-11, 6-28 
EM_SETTABSTOPS message, (vol. 1) 5-11, 6-28 
EM_SETWORDBREAK message, (vol. 1) 5-11, 6-29 
EM_UNDO message, (vol. 1) 5-11, 6-30 
EmptyClipboard function, (vol. 1) 1-59, 4-110 

EMS memory, determining available, (vol. 1) 4-177 
EN_CHANGE message, (vol. 1) 5-16, 6-30 
EN_ERRSPACE message, (vol. 1) 5-16, 6-30 
EN_HSCROLL message, (vol. 1) 5-16, 6-31 
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EN_KILLFOCUS message, (vol. 1) 5-16, 6-31 
EN_MAXTEXT message, (vol. 1) 5-16, 6-31 
EN_SETFOCUS message, (vol. 1) 5-16, 6-32 
EN_UPDATE message, (vol. 1) 5-16, 6-32 
EN_VSCROLL message, (vol. 1) 5-16, 6-33 
ENABLEDUPLEX printer escape, (vol. 2) 12-9 
EnableHardwareInput function, (vol. 1) 1-30, 4-111 
EnableMenultem function, (vol. 1) 1-56, 4-111, 4-311 
ENABLEPAIRKERNING printer escape, (vol. 2) 12-10 
ENABLERELATIVEWIDTHS printer escape, (vol. 2) 
12-11 
EnableWindow function, (vol. 1) 1-29, 4-112 
END_PATH printer escape, (vol. 2) 12-12 to 12-14 
EndDeferWindowPos function, (vol. 1) 1-28, 4-113 
EndDialog function, (vol. 1) 1-44, 4-99, 4-113 
ENDDOC printer escape, (vol. 2) 12-12 
#endif directive, resource compiler, (vol. 2) 8-51 
EndPaint function, (vol. 1) 1-31, 4-114 
Entry point 

creating, (vol. 2) 13-5 

function, (vol. 2) 14-2 
EnumChildWindows function, (vol. 1) 1-57, 4-115 
EnumClipboardFormats function, (vol. 1) 1-59, 4-116 
EnumFonts function, (vol. 1) 2-28, 4-117 
EnumMetaFile function, (vol. 1) 2-41, 4-118 to 4-119 
EnumObjects function, (vol. 1) 2-6, 4-120 
ENUMPAPERBINS printer escape, (vol. 1) 4-91, (vol. 2) 
12-15 
ENUMPAPERMETRICS printer escape, (vol. 2) 12-16 
EnumProps function, (vol. 1) 1-65, 4-121 to 4-122 
EnumTaskWindows function, (vol. 1) 1-57, 4-123 to 
4-124 
Enum Windows function, (vol. 1) 1-57, 4-125 
Epilog, Windows, (vol. 2) 13-4 
EPSPRINTING printer escape, (vol. 2) 12-16 
EQU directive, Cmacro, (vol. 2) 13-3 
EqualRect function, (vol. 1) 1-67, 4-126 
EqualRgn function, (vol. 1) 2-21, 4-126 
errn$ macro, Cmacro, (vol. 2) 14-7 
errnz macro, Cmacro, (vol. 2) 14-8 
Error macros, Cmacro, (vol. 2) 13-9 
ERROR region type, (vol. 1) 4-32, 4-129, 4-158, 4-224, 
4-260, 4-318 to 4-319, 4-359 
ES_AUTOHSCROLL control style, (vol. 1) 4-70, (vol. 
2) 8-41 
ES_AUTOVSCROLL control style, (vol. 1) 4-70, (vol. 
2) 8-40 to 8-41 
ES_CENTER control style, (vol. 1) 4-70, (vol. 2) 8-39 
ES_LEFT control style, (vol. 1) 4-70, (vol. 2) 8-39 
ES_LOWERCASE control style, (vol. 1) 4-70, (vol. 2) 
8-39 
ES_MULTILINE control style, (vol. 1) 4-70, (vol. 2) 8-40 
ES_NOHIDESEL control style, (vol. 1) 4-71, (vol. 2) 


8-41 
ES_OEMCONVERT control style, (vol. 1) 4-71, (vol. 2) 
8-41 
ES_PASSWORD control style, (vol. 1) 4-71, (vol. 2) 8-40 
ES_RIGHT control style, (vol. 1) 4-71, (vol. 2) 8-39 
ES_UPPERCASE control style, (vol. 1) 4-71, (vol. 2) 
8-40 
Escape character 

\a, (vol. 2) 8-10 

\t, (vol. 2) 8-10 
Escape function, (vol. 1) 4-126 
EscapeCommFunction function, (vol. 1) 3-11, 4-127 
Escapes, printer, (vol. 2) 12-1 
EV_BREAK event-mask value, (vol. 1) 4-373 
EV_CTS event-mask value, (vol. 1) 4-373 
EV_DSR event-mask value, (vol. 1) 4-373 
EV_ERR event-mask value, (vol. 1) 4-373 
EV_PERR event-mask value, (vol. 1) 4-373 
EV_RING event-mask value, (vol. 1) 4-373 
EV_RLSD event-mask value, (vol. 1) 4-373 
EV_RXCHAR event-mask value, (vol. 1) 4-373 
EV_RXFLAG event-mask value, (vol. 1) 4-373 
EV_TXEMPTY event-mask value, (vol. 1) 4-373 
EVENPARITY parity type, (vol. 2) 7-23 
ExcludeClipRect function, (vol. 1) 2-22, 4-128 
ExcludeUpdateRgn function, (vol. 1) 1-31, 4-129 
EXETYPE module-definition statement, (vol. 2) 10-4 
Exit point, function, (vol. 2) 14-3 
ExitWindows function, (vol. 1) 3-6, 4-130 
Exporting function, (vol. 2) 10-7 
EXPORTS module-definition statement, (vol. 2) 10-4 
EXPORTS statement, (vol. 2) 10-1 
EXT_DEVICE_CAPS printer escape, (vol. 2) 12-17 to 
12-18 
ExtDeviceMode function, (vol. 1) 2-44, 4-130 to 4-132 
Extents, viewport and window default, (vol. 1) 1-33 
externX macro, Cmacro, (vol. 2) 14-9 
ExtFloodFill function, (vol. 1) 2-25, 4-133 
ExtTextOut function, (vol. 1) 2-27, 4-134 to 4-135 
EXTTEXTOUT printer escape, (vol. 2) 12-19 to 12-20 
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FAR data type, (vol. 2) 7-1 
FAR function type, Cmacro, (vol. 2) 13-10 
FARPROC data type, (vol. 2) 7-1 
FarPtr 

cCall, use with, (vol. 2) 14-9 

macro, Cmacro, (vol. 2) 14-9 
FatalAppExit function, (vol. 1) 3-14, 4-136 
FatalExit function, (vol. 1) 3-14, 4-136 
FF_DECORATIVE font family, (vol. 2) 7-44 
FF_DONTCARE font family, (vol. 2) 7-44 
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FF_MODERN font family, (vol. 2) 7-44 
FF_ROMAN font family, (vol. 2) 7-44 
FF_SCRIPT font family, (vol. 2) 7-44 
FF_SWISS font family, (vol. 2) 7-44 
File 
bitmap, device-independent, format, (vol. 2) 9-1 
clipboard format, (vol. 2) 9-5 
closing, (vol. 1) 4-271 
CMACROS.INC, (vol. 2) 13-4 
creating, (vol. 1) 4-271 
cursor format, (vol. 2) 9-3 
help, displaying, (vol. 1) 4-460 
icon format, (vol. 2) 9-2 
initialization 
application-specific, (vol. 1) 4-199, 4-463 
WINDOWS.H, (vol. 2) 8-15 
metafile format, (vol. 2) 9-6 
module-definition file format, (vol. 2) 10-1 
opening, (vol. 1) 4-294 
positioning the pointer, (vol. 1) 4-274 
reading, (vol. 1) 4-297 
writing, (vol. 1) 4-300 
Filling mode 
ALTERNATE, (vol. 1) 4-58, 4-389 
WINDING, (vol. 1) 4-58, 4-389 
FillRect function, (vol. 1) 1-31, 4-137 
FillRgn function, (vol. 1) 2-21, 4-138 
Filters, installing, (vol. 1) 1-65 
FindAtom function, (vol. 1) 3-9, 4-138 
FindResource function, (vol. 1) 3-7, 4-139 
FindWindow function, (vol. 1) 1-57, 4-140 
Fixed-pitch font attribute, (vol. 1) 2-35 
FIXED resource-compiler key word, (vol. 2) 8-2 to 8-3, 
8-5 to 8-6, 8-9, 8-13 
FlashWindow function, (vol. 1) 1-59, 4-141 
Flat memory model, (vol. 2) E-2, E-5 
FloodFill function, (vol. 1) 2-25, 4-141 
FlushComm function, (vol. 1) 3-11, 4-142 
FLUSHOUTPUT printer escape, (vol. 2) 12-21 
Font functions, (vol. 1) 2-28 to 2-29 
Font mapping characteristics, (vol. 1) 2-38 to 2-39 
FONT resource-compiler key word, (vol. 2) 8-2 
FONT resource statement, (vol. 2) 8-19 
Font Selection, (vol. 1) 2-40 
FONTINEFO data structure, (vol. 1) 6-100, (vol. 2) 7-34 
Fonts 
average character width, (vol. 1) 2-35 
character sets 
ANSI, (vol. 1) 2-35 
described, (vol. 1) 2-34 
OEM, (vol. 1) 2-35 
printer, (vol. 1) 2-35 
vendor specific, (vol. 1) 2-35 


control, current, (vol. 1) 6-62 

default, (vol. 1) 1-33 

digitized aspect, (vol. 1) 2-36 

family 

described, (vol. 1) 2-29 
italic, bold, and underline, (vol. 1) 2-32 

leading, (vol. 1) 2-33 to 2-34 

logical, creating, (vol. 1) 4-48, 4-51, (vol. 2) 7-40 

maximum character width, (vol. 1) 2-36 

overhang, (vol. 1) 2-36 

pitch, (vol. 1) 2-35 

resource, (vol. 2) 8-2 

setting in control, (vol. 1) 6-99 
Formats, clipboard, (vol. 1) 4-370 
Formatted text, styles, (vol. 1) 1-41 
FrameRect function, (vol. 1) 1-31, 4-143 
FrameRgn function, (vol. 1) 2-21, 4-143 
FreeLibrary function, (vol. 1) 3-2, 4-144 
FreeModule function, (vol. 1) 3-2, 4-144 
FreeProcInstance function, (vol. 1) 3-2, 4-145 
FreeResource function, (vol. 1) 3-7, 4-145 
FreeSelector function, (vol. 1) 3-5, 4-146 
Function macros, Cmacro, (vol. 2) 13-8 
Function register, (vol. 2) 13-8 
Functions 

additional, (vol. 1) 1-67 

bitmap, (vol. 1) 2-25 to 2-27 

bounding rectangles, (vol. 1) 2-25 

callback, (vol. 2) 13-5 

caret, (vol. 1) 1-60 to 1-61 

clipboard, (vol. 1) 1-58 

clipping, (vol. 1) 2-22 

coordinates, (vol. 1) 2-20, 2-23 

defining in assembly language, (vol. 2) 14-4 

device context attributes, (vol. 1) 2-3 

device contexts, (vol. 1) 2-2 

displaying, (vol. 1) 1-28 

drawing tools, (vol. 1) 2-5 

entry point, (vol. 2) 14-2 

environment, (vol. 1) 2-47 

error, (vol. 1) 1-59 

exit point, (vol. 2) 14-3 

far, (vol. 2) 14-5 

filters, (vol. 1) 1-63 

font, (vol. 1) 2-28 

hardware, (vol. 1) 1-30 

hook, (vol. 1) 1-63 

information, (vol. 1) 1-57 

input, (vol. 1) 1-29 

main loop, (vol. 1) 1-4 

mapping drawing attributes, (vol. 1) 2-15 

menu, (vol. 1) 1-56 

metafile, (vol. 1) 2-41 
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movement, (vol. 1) 1-28 
near, (vol. 2) 14-5 
obtaining device information, (vol. 1) 2-5 
painting, (vol. 1) 1-31 
printer control, (vol. 1) 2-44 
property lists, (vol. 1) 1-65, 1-67 
public, (vol. 2) 14-5 
rectangle 
coordinates, (vol. 1) 1-67 
specifying, (vol. 1) 1-67 
regions, (vol. 1) 2-21 
system, (vol. 1) 1-58 
text, (vol. 1) 2-27 
window, (vol. 1) 1-6 


G 


GCL_MENUNAME option, (vol. 1) 4-368 
GCL_WNDPROC option, (vol. 1) 4-154, 4-368 
GCW_CBCLSEXTRA option, (vol. 1) 4-155, 4-369 
GCW_CBWNDEXTRA option, (vol. 1) 4-155, 4-369 
GCW_HBRBACKGROUND option, (vol. 1) 4-155, 
4-369 
GCW_HCURSOR option, (vol. 1) 4-155, 4-369 
GCW_HICON option, (vol. 1) 4-155, 4-369 
GCW_HMODULE option, (vol. 1) 4-155 
GCW_STYLE option, (vol. 1) 4-155, 4-369 
GDI functions 
brushes, predefined, (vol. 1) 2-7 
color palettes, (vol. 1) 2-10 
drawing attribute functions 
background mode and color, (vol. 1) 2-14 
described, (vol. 1) 2-13 
mapping funtions, (vol. 1) 2-15 
stretch mode and text color, (vol. 1) 2-14 
drawing tool functions, (vol. 1) 2-5 
mapping functions, (vol. 1) 2-15 
mapping modes 
constraining, (vol. 1) 2-17 to 2-18 
transformation equations, (vol. 1) 2-18 
obtaining device information, (vol. 1) 2-5 
pens, predefined, (vol. 1) 2-8 
selecting fonts, (vol. 1) 2-36 
using drawing tools, (vol. 1) 2-6 
working with color palettes, (vol. 1) 2-11 
GetActive Window function, (vol. 1) 1-29, 4-147 
GetAspectRatioFilter function, (vol. 1) 2-36, 4-147 
GetAsyncKeyState function, (vol. 1) 1-30, 4-147 
GetAtomHandle function, (vol. 1) 3-9, 4-148 
GetAtomName function, (vol. 1) 3-9, 4-148 
GetBitmapBits function, (vol. 1) 2-25, 4-149 
GetBitmapDimension function, (vol. 1) 2-25, 4-149 
GetBkColor function, (vol. 1) 2-14, 4-150 


GetBkMode function, (vol. 1) 2-14, 4-150 
GetBrushOrg function, (vol. 1) 2-6, 4-150 

GetB Value function, (vol. 1) 2-9, 4-151 

GetCapture function, (vol. 1) 1-29, 4-151 
GetCaretBlinkTime function, (vol. 1) 1-60, 4-151 
GetCaretPos function, (vol. 1) 1-60, 4-152 
GetCharWidth function, (vol. 1) 2-28, 4-152 
GetClassInfo function, (vol. 1) 1-7, 4-153 
GetClassLong function, (vol. 1) 1-7, 4-153 
GetClassName function, (vol. 1) 1-7, 4-154 
GetClassWord function, (vol. 1) 1-7, 4-155 
GetClientRect function, (vol. 1) 1-28, 4-156 
GetClipboardData function, (vol. 1) 1-59, 4-156 
GetClipboardFormatName function, (vol. 1) 1-59, 4-157 
GetClipboardOwner function, (vol. 1) 1-59, 4-157 
GetClipboard Viewer function, (vol. 1) 1-59, 4-158 
GetClipBox function, (vol. 1) 2-22, 4-158 
GetCodeHandle function, (vol. 1) 3-2, 4-159 
GetCodelnfo function, (vol. 1) 3-5, 4-159 to 4-160 
GETCOLORTABLE printer escape, (vol. 2) 12-21 
GetCommError function, (vol. 1) 3-11, 4-161 
GetCommEventMask function, (vol. 1) 3-11, 4-162 
GetCommState function, (vol. 1) 3-11, 4-162 
GetCurrentPDB function, (vol. 1) 3-7, 4-163 
GetCurrentPosition function, (vol. 1) 4-163 
GetCurrentTask function, (vol. 1) 3-7, 4-164 
GetCurrentTime function, (vol. 1) 1-29, 1-58, 4-164 
GetCursorPos function, (vol. 1) 1-62, 4-164 

GetDC function, (vol. 1) 1-31, 4-165 

GetDCOrg function, (vol. 1) 2-2, 4-165 

GetDesktop Window function, (vol. 1) 4-166 
GetDeviceCaps function, (vol. 1) 4-166 to 4-169 
GetDialogBase Units function, (vol. 1) 1-44, 1-47, 4-170, 
4-304, 6-28, 6-44, (vol. 2) 7-35, 8-14, 8-21 to 8-30, 8-32 
to 8-35 

GetDIBits function, (vol. 1) 2-13, 2-26, 4-168, 4-171 
GetDlgCtrlID function, (vol. 1) 1-44, 4-172 
GetDlgItem function, (vol. 1) 1-44, 4-173 
GetDlgItemInt function, (vol. 1) 1-44, 4-173 
GetDlgItemText function, (vol. 1) 1-44, 4-174 
GetDOSEnvironment function, (vol. 1) 3-7, 4-175 
GetDoubleClickTime function, (vol. 1) 1-29, 4-175 
GetDriveType function, (vol. 1) 3-13, 4-175 
GetEnvironment function, (vol. 1) 2-47, 4-176 
GETEXTENDEDTEXTMETRICS printer escape, (vol. 
2) 12-21 to 12-25 

GETEXTENTTABLE printer escape, (vol. 2) 12-26 
GETFACENAME printer escape, (vol. 2) 12-27 
GetFocus function, (vol. 1) 1-29, 4-177 
GetFreeSpace function, (vol. 1) 3-3, 4-177 

GetG Value function, (vol. 1) 2-9, 4-178 
GetInputState function, (vol. 1) 1-30, 4-178 
GetInstanceData function, (vol. 1) 3-2, 4-178 
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GetKBCodePage function, (vol. 1) 1-31, 4-179 
GetKeyboardState function, (vol. 1) 1-30, 4-180 
GetKeyboardType function, (vol. 1) 4-181 
GetKeyNameText function, (vol. 1) 1-30, 4-182 
GetKeyState function, (vol. 1) 1-30, 4-183 
GetLastActivePopup function, (vol. 1) 1-7, 4-183 
GetMapMode function, (vol. 1) 2-15, 4-184 

GetMenu function, (vol. 1) 1-56, 4-184 
GetMenuCheckMarkDimensions function, (vol. 1) 1-56, 
4-184 

GetMenultemCount function, (vol. 1) 1-56, 4-185 
GetMenultemID function, (vol. 1) 1-56, 4-185 
GetMenuState function, (vol. 1) 1-56, 4-185 to 4-186 
GetMenuString function, (vol. 1) 1-56, 4-187 
GetMessage function, (vol. 1) 1-2, 4-188 
GetMessagePos function, (vol. 1) 1-2, 4-189 
GetMessageTime function, (vol. 1) 1-2, 4-189 
GetMetaFile function, (vol. 1) 2-41, 4-190 
GetMetaFileBits function, (vol. 1) 2-41, 4-190 
GetModuleFileName function, (vol. 1) 3-2, 4-190 
GetModuleHandle function, (vol. 1) 3-2, 4-191 
GetModuleUsage function, (vol. 1) 3-2, 4-191 
GetNearestColor function, (vol. 1) 2-9, 4-192 
GetNearestPaletteIndex function, (vol. 1) 2-10, 4-192 
GetNextDlgGroupltem function, (vol. 1) 1-44, 4-192 
GetNextDlgTabItem function, (vol. 1) 1-44, 4-193 
GetNextWindow function, (vol. 1) 1-58, 4-194 
GetNumTasks function, (vol. 1) 3-7, 4-194 

GetObject function, (vol. 1) 2-6, 4-195 
GETPAIRKERNTABLE printer escape, (vol. 2) 12-27 to 
12-28 

GetPaletteEntries function, (vol. 1) 2-10, 4-195 
GetParent function, (vol. 1) 1-58, 4-196 
GETPHYSPAGESIZE printer escape, (vol. 2) 12-29 
GetPixel function, (vol. 1) 2-26, 4-196 
GetPolyFillMode function, (vol. 1) 2-14, 4-197 
GETPRINTINGOFFSET printer escape, (vol. 2) 12-29 
GetPriorityClipboardFormat function, (vol. 1) 1-59, 4-197 
GetPrivateProfileInt function, (vol. 1) 3-10, 4-198 to 
4-199 

GetPrivateProfileString function, (vol. 1) 3-10, 4-199 to 
4-200 

GetProcAddress function, (vol. 1) 3-2, 4-200 
GetProfileInt function, (vol. 1) 3-10, 4-201 
GetProfileString function, (vol. 1) 3-10, 4-202 
GetProp function, (vol. 1) 1-65, 4-203 

GetRgnBox function, (vol. 1) 2-21, 4-203 

GetROP2 function, (vol. 1) 2-14, 4-204 

GetRValue function, (vol. 1) 2-9, 4-204 
GETSCALINGFACTOR printer escape, (vol. 2) 12-30 
GetScrollPos function, (vol. 1) 1-53, 4-205 
GetScrollRange function, (vol. 1) 1-53, 4-205 to 4-206 
GETSETPAPERBINS printer escape, (vol. 2) 12-30 to 


12-31 

GETSETPAPERMETRICS printer escape, (vol. 2) 12-32 
GETSETPAPERORIENT printer escape, (vol. 2) 12-32 
GETSETPAPERORIENTATION printer escape, (vol. 2) 
12-33 

GETSETSCREENPARAMS printer escape, (vol. 2) 
12-33 to 12-34 

GetStockObject function, (vol. 1) 2-6, 4-207 
GetStretchBltMode function, (vol. 1) 2-14, 4-208 
GetSubMenu function, (vol. 1) 1-56, 4-209, (vol. 2) 7-17 
GetSysColor function, (vol. 1) 1-58, 4-209, 4-250 
GetSysModal Window function, (vol. 1) 4-210 
GetSystemDirectory function, (vol. 1) 3-13, 4-210 
GetSystemMenu function, (vol. 1) 1-57, 4-211, 6-106 
GetSystemMetrics function, (vol. 1) 1-58, 4-212 
GetSystemPaletteEntries function, (vol. 1) 2-10, 4-213 
GetSystemPaletteUse function, (vol. 1) 2-10, 4-214 
GetTabbedTextExtent function, (vol. 1) 2-27, 4-215 
GETTECHNOLOGY printer escape, (vol. 2) 12-35 
GetTempDrive function, (vol. 1) 3-13, 4-216 
GetTempFileName function, (vol. 1) 3-13, 4-216 
GetTextAlign function, (vol. 1) 2-27, 4-217 to 4-218 
GetTextCharacterExtra function, (vol. 1) 4-219 
GetTextColor function, (vol. 1) 2-14, 4-219 
GetTextExtent function, (vol. 1) 2-27, 4-220 
GetTextFace function, (vol. 1) 2-27, 4-220 
GetTextMetrics function, (vol. 1) 2-27, 4-221 
GetThresholdEvent function, (vol. 1) 3-12, 4-221 
GetThresholdStatus function, (vol. 1) 3-12, 4-222 
GetTickCount function, (vol. 1) 1-29, 4-222 
GetTopWindow function, (vol. 1) 1-58, 4-222 
GETTRACKKERNTABLE printer escape, (vol. 2) 12-35 
to 12-36 

GetUpdateRect function, (vol. 1) 1-31, 4-223 
GetUpdateRgn function, (vol. 1) 1-31, 4-223 
GETVECTORBRUSHSIZE printer escape, (vol. 2) 12-37 
GETVECTORPENSIZE printer escape, (vol. 2) 12-37 
GetVersion function, (vol. 1) 3-2, 4-224 
GetViewportExt function, (vol. 1) 2-15, 4-225 
GetViewportOrg function, (vol. 1) 2-15, 4-225 
GetWindow function, (vol. 1) 1-58, 4-225 
GetWindowDC function, (vol. 1) 1-31, 4-226 
GetWindowExt function, (vol. 1) 2-15, 4-227 
GetWindowLong function, (vol. 1) 1-7, 1-16, 4-228 
GetWindowOrg function, (vol. 1) 2-15, 4-228 
GetWindowRect function, (vol. 1) 1-28, 4-229 
GetWindowsDirectory function, (vol. 1) 3-13, 4-229 
GetWindowTask function, (vol. 1) 1-58, 4-230 
GetWindowText function, (vol. 1) 1-28, 4-230 
GetWindowTextLength function, (vol. 1) 1-29, 4-231 
GetWindowWord function, (vol. 1) 1-7, 4-231 
GetWinFlags function, (vol. 1) 3-3, 4-232 
GetWinMem32Version, (vol. 2) E-3, E-10 
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Global variable, Cmacro, (vol. 2) 14-11 
Global16PointerAlloc function, (vol. 2) E-3, E-10 to E-11 
Global16PointerFree function, (vol. 2) E-3, E-11 
Global32Alloc function, (vol. 2) E-3, E-12 to E-13 
Global32CodeAlias function, (vol. 2) E-3, E-13 to E-14 
Global32CodeAliasFree function, (vol. 2) E-3, E-14 
Global32Free function, (vol. 2) E-3, E-14 to E-15 
Global32Realloc function, (vol. 2) E-3, E-15 
GlobalAddAtom function, (vol. 1) 3-9, 4-233 
GlobalAlloc function, (vol. 1) 3-3, 4-233 to 4-234 
GlobalCompact function, (vol. 1) 3-3, 4-177, 4-235 
GlobalDeleteAtom function, (vol. 1) 3-9, 4-235 
GlobalDiscard function, (vol. 1) 3-3, 4-236 
GlobalDosAlloc function, (vol. 1) 3-3, 4-236 
GlobalDosFree function, (vol. 1) 3-3, 4-237 
GlobalFindAtom function, (vol. 1) 3-10, 4-237 
GlobalFix function, (vol. 1) 3-5, 4-238 
GlobalFlags function, (vol. 1) 3-3, 4-238 
GlobalFree function, (vol. 1) 3-3, 4-239 
GlobalGetAtomName function, (vol. 1) 3-10, 4-240 
GLOBALHANDLE data type, (vol. 2) 7-2 
GlobalHandle function, (vol. 1) 3-3, 4-240 
GlobalLock function, (vol. 1) 3-3, 4-241 
GlobalLRUNewest function, (vol. 1) 3-3, 4-241 
GlobalLRUOldest function, (vol. 1) 3-3, 4-242 
GlobalNotify function, (vol. 1) 3-3, 4-242 
GlobalPageLock function, (vol. 1) 3-6, 4-243 
GlobalPageUnlock function, (vol. 1) 3-6, 4-244 
GlobalReAlloc function, (vol. 1) 3-3, 4-244 to 4-245 
GlobalSize function, (vol. 1) 3-3, 4-246 
GlobalUnfix function, (vol. 1) 3-6, 4-247 
GlobalUnlock function, (vol. 1) 3-4, 4-247 
GlobalUnwire function, (vol. 1) 3-4, 4-248 
GlobalWire function, (vol. 1) 3-4, 4-248 
globalX macro, Cmacro, (vol. 2) 14-10 
GMEM_DDESHARE option, (vol. 1) 4-234, 4-239 
GMEM_DISCARDABLE option, (vol. 1) 4-234, 4-239, 
4-245 
GMEM_DISCARDED option, (vol. 1) 4-239 
GMEM_FIXED option, (vol. 1) 4-234 
GMEM_MODIFY option, (vol. 1) 4-245 
GMEM_MOVEABLE option, (vol. 1) 4-234, 4-245 
GMEM_NOCOMPACT option, (vol. 1) 4-234, 4-246 
GMEM_NODISCARD option, (vol. 1) 4-234, 4-246 
GMEM_NOT_BANKED option, (vol. 1) 4-177, 4-234, 
4-239 
GMEM_NOTIFY option, (vol. 1) 4-234 
GMEM_ZEROINIT option, (vol. 1) 4-234, 4-246 
Graphics device interface, defined, (vol. 1) xvii 
GRAY_BRUSH stock object, (vol. 1) 4-207 
GRAYED ment-item option, (vol. 2) 7-51 
GRAYED option 

MENUITEM resource statement, (vol. 2) 8-11 


POPUP resource statement, (vol. 2) 8-12 
GrayString function, (vol. 1) 1-31, 4-249 to 4-251 
Group box, BUTTON class, (vol. 2) 8-27 
GROUPBOxX resource statement 

described, (vol. 2) 8-27 to 8-28 

DIALOG resource statement, (vol. 2) 8-20 
GW_CHILD option, (vol. 1) 4-226 
GW_HWNDFIRST option, (vol. 1) 4-226 
GW_HWNDLAST option, (vol. 1) 4-226 
GW_HWNDNEXT option, (vol. 1) 4-194, 4-226 
GW_HWNDPREYV option, (vol. 1) 4-194, 4-226 
GW_OWNER option, (vol. 1) 4-226 
GWL_EXSTYLE option, (vol. 1) 4-228, 4-416 
GWL_STYLE option, (vol. 1) 4-228, 4-416 
GWL_WNDPROC option, (vol. 1) 4-228, 4-416 
GWW_HINSTANCE option, (vol. 1) 4-231, 4-428 
GWW_HWNDPARENT option, (vol. 1) 4-231 
GWW_ID option, (vol. 1) 4-231, 4-428 


H 


HANDLE data type, (vol. 2) 7-2 
Handle table, (vol. 2) 7-38 
Handles 

instance, (vol. 1) 1-12 

task, obtaining, (vol. 1) 4-164 
HANDLETABLE data structure, (vol. 2) 7-38 
HBITMAP data type, (vol. 2) 7-2 
HBRUSH data type, (vol. 2) 7-2 
HCURSOR data type, (vol. 2) 7-2 
HDC data type, (vol. 2) 7-2 
Heap, local, (vol. 2) 10-5 
HEAPSIZE module-definition statement, (vol. 2) 10-5 
HEAPSIZE statement 

described, (vol. 2) 10-1 

syntax, (vol. 2) 10-5 
Help application, (vol. 1) 4-460 
HELP_CONTEXT option, (vol. 1) 4-460 
HELP_HELPONHELP option, (vol. 1) 4-460 
HELP_INDEX option, (vol. 1) 4-460 
HELP_KEY option, (vol. 1) 4-461 
HELP_MULTIKEY option, (vol. 1) 4-461 
HELP option, MENUITEM resource statement, (vol. 2) 
8-10 
HELP_QUIT option, (vol. 1) 4-461 
HELP_SETINDEX, (vol. 1) 4-461 
HFONT data type, (vol. 2) 7-2 
HIBYTE utility macro, (vol. 1) 3-13, 4-252 
HICON data type, (vol. 2) 7-2 
HideCaret function, (vol. 1) 1-60, 4-252 
HiliteMenultem function, (vol. 1) 1-57, 4-253 
HIWORD utility macro, (vol. 1) 3-13, 4-171, 4-254 
HMENU data type, (vol. 2) 7-2 
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HOLLOW_BRUSH stock object, (vol. 1) 4-207 

Hook chain, (vol. 1) 4-82 

Hook function, (vol. 1) 4-82 

HORZRES device capability, (vol. 1) 4-167 
HORZSIZE device capability, (vol. 1) 4-167 
HPALETTE data type, (vol. 2) 7-2 

HPEN data type, (vol. 2) 7-2 

HRGN data type, (vol. 2) 7-2 

HS_BDIAGONAL brush hatch style, (vol. 1) 4-52, (vol. 
2) 7-40 

HS_CROSS brush hatch style, (vol. 1) 4-52, (vol. 2) 7-40 
HS_DIAGCROSS brush hatch style, (vol. 1) 4-52, (vol. 
2) 7-40 

HS_FDIAGONAL brush hatch style, (vol. 1) 4-52, (vol. 
2) 7-40 


HS_HORIZONTAL brush hatch style, (vol. 1) 4-52, (vol. 


2) 7-40 

HS_VERTICAL brush hatch style, (vol. 1) 4-52, (vol. 2) 
7-40 

HSTR data type, (vol. 2) 7-2 

HTBOTTOM mouse-position code, (vol. 1) 6-85 
HTBOTTOMLEFT mouse-position code, (vol. 1) 6-85 
HTBOTTOMRIGHT mouse-position code, (vol. 1) 6-85 
HTCAPTION mouse-position code, (vol. 1) 6-85 
HTCLIENT mouse-position code, (vol. 1) 6-85 
HTERROR mouse-position code, (vol. 1) 6-85 
HTGROWBOX mouse-position code, (vol. 1) 6-85 
HTHSCROLL mouse-position code, (vol. 1) 6-85 
HTLEFT mouse-position code, (vol. 1) 6-85 

HTMENU mouse-position code, (vol. 1) 6-85 
HTNOWHERE mouse-position code, (vol. 1) 6-85 
HTREDUCE mouse-position code, (vol. 1) 6-85 
HTRIGHT mouse-position code, (vol. 1) 6-85 

HTSIZE mouse-position code, (vol. 1) 6-85 
HTSYSMENU mouse-position code, (vol. 1) 6-85 
HTTOP mouse-position code, (vol. 1) 6-85 
HTTOPLEFT mouse-position code, (vol. 1) 6-85 
HTTOPRIGHT mouse-position code, (vol. 1) 6-86 
HTTRANSPARENT mouse-position code, (vol. 1).6-86 
HTVSCROLL mouse-position code, (vol. 1) 6-86 
HTZOOM mouse-position code, (vol. 1) 6-86 
hWindowMenu, (vol. 2) 7-17 


/ 


IBM PC extended character set, (vol. 2) D-1 
Icon 

class, (vol. 1) 1-12 

drawing, (vol. 1) 1-39 

file format, (vol. 2) 9-2 
Icon resource, (vol. 2) 8-2 
ICON resource-compiler key word, (vol. 2) 8-2 
ICON resource statement 


described, (vol. 2) 8-33 

DIALOG resource statement, (vol. 2) 8-20 
IDABORT menu-item value, (vol. 1) 4-307 
IDC_ARROW cursor type, (vol. 1) 4-278 
IDC_CROSS cursor type, (vol. 1) 4-278 
IDC_IBEAM cursor type, (vol. 1) 4-278 
IDC_ICON cursor type, (vol. 1) 4-278 
IDC_SIZE, (vol. 1) 4-278 
IDC_SIZENESW cursor type, (vol. 1) 4-278 
IDC_SIZENS cursor type, (vol. 1) 4-278 
IDC_SIZENWSE cursor type, (vol. 1) 4-278 
IDC_SIZEWE cursor type, (vol. 1) 4-278 
IDC_UPARROW cursor type, (vol. 1) 4-278 
IDC_WAIT cursor type, (vol. 1) 4-278 
IDCANCEL menu-item value, (vol. 1) 4-132, 4-307 
IDI_APPLICATION icon type, (vol. 1) 4-279 
IDI_ASTERISK icon type, (vol. 1) 4-279 
IDI_EXCLAMATION icon type, (vol. 1) 4-279 
IDI_LHAND icon type, (vol. 1) 4-279 
IDI_QUESTION icon type, (vol. 1) 4-279 
IDIGNORE menv-item value, (vol. 1) 4-307 
IDNO menv-item value, (vol. 1) 4-307 
IDOK menu-item value, (vol. 1) 4-132, 4-307 
IDRETRY menu-item value, (vol. 1) 4-307 
IDYES menu-item value, (vol. 1) 4-307 
IE_BADID error return value for OpenComm function, 
(vol. 1) 4-322 
IE_BAUDRATE error return value for OpenComm 
function, (vol. 1) 4-322 
IE_BYTESIZE error return value for OpenComm 
function, (vol. 1) 4-322 
IE_DEFAULT error return value for OpenComm 
function, (vol. 1) 4-322 
IE_HARDWARE error return value for OpenComm 
function, (vol. 1) 4-322 
IE_MEMORY error return value for OpenComm 
function, (vol. 1) 4-322 
IE_NOPEN error return value for OpenComm function, 
(vol. 1) 4-322 
IE_OPEN error return value for OpenComm function, 
(vol. 1) 4-322 
#if directive, resource compiler, (vol. 2) 8-49 
#ifdef directive, resource compiler, (vol. 2) 8-48 
#ifndef directive, resource compiler, (vol. 2) 8-49 
IMPORTS module-definition statement, (vol. 2) 10-6 
IMPORTS statement, (vol. 2) 10-1, 10-6 
INACTIVE option 

MENUITEM resource statement, (vol. 2) 8-10 

POPUP resource statement, (vol. 2) 8-11 
INCLUDE command, Cmacro, (vol. 2) 13-4 
#include directive 

resource compiler, (vol. 2) 8-47 

when required with STYLE statement, (vol. 2) 8-15 
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INCLUDE environmental variable, (vol. 2) 8-47 
IncUpdate, (vol. 2) 7-55 
InflateRect function, (vol. 1) 1-67 to 1-68, 4-255 
InitAtomTable function, (vol. 1) 3-10, 4-255 
Initialization file, application-specific 

getting integer from, (vol. 1) 4-199 

getting string from, (vol. 1) 4-199 

writing to, (vol. 1) 4-463 
InSendMessage function, (vol. 1) 1-2, 4-256 
InsertMenu function, (vol. 1) 1-26, 1-57, 4-54, 4-59, 
4-211, 4-256 to 4-258, 6-106, (vol. 2) 7-38 
Instructions, coding sequences, (vol. 2) 13-9 
int data type, (vol. 2) 7-2 
Integer messages, (vol. 1) 6-1 
Intercharacter spacing, default, (vol. 1) 1-33 
Internal data structures, (vol. 1) 1-16 
Interrupt 

function request (21H), (vol. 1) 4-104 

function request (5CH), (vol. 1) 4-315 
IntersectClipRect function, (vol. 1) 2-22, 4-259 
IntersectRect function, (vol. 1) 1-67 to 1-68, 4-260 
InvalidateRect function, (vol. 1) 1-31, 4-261 
InvalidateRgn function, (vol. 1) 1-32, 4-261 
InvertRect function, (vol. 1) 1-32, 4-262 
InvertRen function, (vol. 1) 2-21, 4-263 
IsCharAlpha function, (vol. 1) 3-8, 4-263 
IsCharAlphaNumeric function, (vol. 1) 3-8, 4-264 
IsCharLower function, (vol. 1) 3-8, 4-264 
IsCharUpper function, (vol. 1) 3-8, 4-264 
IsChild function, (vol. 1) 1-58, 4-265 
IsClipboardFormatA vailable function, (vol. 1) 1-59, 4-265 
IsDialogMessage function, (vol. 1) 1-44, 4-266 
IsDlgButtonChecked function, (vol. 1) 1-44, 4-266 
IsIconic function, (vol. 1) 1-29, 4-267 
IsRectEmpty function, (vol. 1) 1-68, 4-267 
IsWindow function, (vol. 1) 1-58, 4-268 
IsWindowEnabled function, (vol. 1) 1-30, 4-268 
IsWindowVisible function, (vol. 1) 1-29, 4-269 
IsZoomed function, (vol. 1) 1-29, 4-269 


K 


Key 
BACKSPACE, (vol. 2) 8-36 
CONTROL, (vol. 2) 8-8 
editing, (vol. 2) 8-30 
getting name, (vol. 1) 4-182 
SHIFT, (vol. 2) 8-8 
TAB, (vol. 2) 8-17 

Key word, resource-compiler 
BITMAP, (vol. 2) 8-2 
CURSOR, (vol. 2) 8-2 
DISCARDABLE, (vol. 2) 8-2, 8-4 to 8-6, 8-9, 8-14 


FIXED, (vol. 2) 8-2 to 8-3, 8-5 to 8-6, 8-9, 8-13 
FONT, (vol. 2) 8-2 
ICON, (vol. 2) 8-2 
LOADONCALL, (vol. 2) 8-2 to 8-3, 8-5 to 8-6, 8-9, 8-13 
MOVEABLE, (vol. 2) 8-2, 8-4 to 8-6, 8-9, 8-14 
PRELOAD, (vol. 2) 8-2 to 8-4, 8-6, 8-9, 8-13 

Keyboard, using with dialog boxes, (vol. 1) 1-52 

KillTimer function, (vol. 1) 1-30, 4-270 


L 


Label 

name, (vol. 2) 14-4, 14-6 

public, (vol. 2) 13-7 
labelX macro, Cmacro, (vol. 2) 14-11 
Language, assembly, (vol. 2) 13-1 
LB_ADDSTRING message, (vol. 1) 5-12, 6-34 to 6-35, 
6-39, 6-41, (vol. 2) 7-27, 7-38, 7-49 
LB_DELETESTRING message, (vol. 1) 5-12, 6-34, 6-57 
LB_DIR message, (vol. 1) 5-12, 6-35 
LB_FINDSTRING message, (vol. 1) 5-12, 6-35 
LB_GETCOUNT message, (vol. 1) 5-12, 6-36 
LB_GETCURSEL message, (vol. 1) 5-12, 6-36 
LB_GETHORIZONTALEXTENT message, (vol. 1) 
5-12, 6-36 
LB_GETITEMDATA message, (vol. 1) 5-12, 6-37 
LB_GETITEMRECT message, (vol. 1) 5-12, 6-37 
LB_GETSEL message, (vol. 1) 5-12, 6-37 
LB_GETSELCOUNT message, (vol. 1) 5-12, 6-38 
LB_GETSELITEMS message, (vol. 1) 5-12, 6-38 
LB_GETTEXT message, (vol. 1) 5-12, 6-38 
LB_GETTEXTLEN message, (vol. 1) 5-12, 6-39 
LB_GETTOPINDEX message, (vol. 1) 5-12, 6-39 
LB_INSERTSTRING message, (vol. 1) 5-12, 6-34 to 
6-35, 6-39 to 6-41, (vol. 2) 7-27, 7-38, 7-49 
LB_RESETCONTENT message, (vol. 1) 5-13, 6-40, 6-57 
LB_SELECTSTRING message, (vol. 1) 5-13, 6-40 
LB_SELITEMRANGE message, (vol. 1) 5-13, 6-41 
LB_SETCOLUMNWIDTH message, (vol. 1) 4-72, 5-13, 
6-42, (vol. 2) 8-42 
LB_SETCURSEL message, (vol. 1) 5-13, 6-42 
LB_SETHORIZONTALEXTENT message, (vol. 1) 
5-13, 6-42 
LB_SETITEMDATA message, (vol. 1) 5-13, 6-37, 6-43 
LB_SETSEL message, (vol. 1) 5-13, 6-43 
LB_SETTABSTOPS message, (vol. 1) 5-13, 6-44 
LB_SETTOPINDEX message, (vol. 1) 5-13, 6-44 
LBN_DBLCLK message, (vol. 1) 5-16, 6-45 
LBN_ERRSPACE message, (vol. 1) 5-16, 6-45 
LBN_KILLFOCUS message, (vol. 1) 5-16, 6-45 
LBN_SELCHANGE message, (vol. 1) 5-16, 6-46 
LBN_SETFOCUS message, (vol. 1) 5-16, 6-46 
LBS_EXTENDEDSEL control style, (vol. 1) 4-71, (vol. 
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2) 8-42 
LBS_HASSTRINGS control style, (vol. 1) 4-72, 6-34 to 
6-35, 6-37, 6-39 to 6-41, (vol. 2) 8-42 
LBS_MULTICOLUMN control style, (vol. 1) 4-72, 6-42, 
(vol. 2) 8-42 
LBS_MULTIPLESEL control style, (vol. 1) 4-72, (vol. 
2) 8-42 
LBS_NOINTEGRALHEIGHT control style, (vol. 2) 8-42 
LBS_NOREDRAW control style, (vol. 1) 4-72, (vol. 2) 
8-42 
LBS_NOTIFY control style, (vol. 1) 4-72, (vol. 2) 8-42 
LBS_OWNERDRAWFIXED control style, (vol. 1) 4-72, 
(vol. 2) 8-42 
LBS_OWNERDRAWVARIABLE control style, (vol. 1) 
4-72, (vol. 2) 8-42 
LBS_SORT control style, (vol. 1) 4-72, (vol. 2) 8-42 
LBS_STANDARD control style, (vol. 1) 4-72, (vol. 2) 
8-41 
LBS_WANTKEYBOARDINPUT control style, (vol. 2) 
8-43 
_Iclose function, (vol. 1) 3-14, 4-271 
_Icreat function, (vol. 1) 3-14, 4-271 
Library 
C-language, (vol. 2) 13-5 
linking, (vol. 2) 13-5 
Windows, (vol. 2) 13-5 
Library module, (vol. 2) 10-7 
LIBRARY module-definition statement, (vol. 2) 10-7 
LIBRARY statement, (vol. 2) 10-1, 10-7 
LimitEMSPages function, (vol. 1) 3-4, 4-272 
Line-output functions 
coordinates, (vol. 1) 2-23 
pen styles, colors and widths, (vol. 1) 2-23 
LINECAPS device capability, (vol. 1) 4-169 
LineDDA function, (vol. 1) 2-22, 4-272 
LineTo function, (vol. 1) 2-22, 4-273 
List box 
directory listings, (vol. 1) 1-49 
horizontal scrolling, (vol. 1) 6-36, 6-42 
owner-draw, (vol. 1) 1-50, (vol. 2) 7-26 
deleted item, (vol. 1) 6-57 
measuring, (vol. 2) 7-48 
sorting, (vol. 1) 6-53, (vol. 2) 7-19 
tab stops in, (vol. 1) 6-44 
LISTBOX control class 
control styles, (vol. 2) 8-26, 8-41 
described, (vol. 1) 4-65, (vol. 2) 8-26, 8-36 
LISTBOX resource statement 
described, (vol. 2) 8-26 
DIALOG resource statement, (vol. 2) 8-20 
_llseek function, (vol. 1) 3-14, 4-274 
LMEM_DISCARDABLE option, (vol. 1) 4-285, 4-287, 
4-290 


LMEM_DISCARDED option, (vol. 1) 4-287 
LMEM_FIXED option, (vol. 1) 4-285 
LMEM_MODIFY option, (vol. 1) 4-285, 4-290 
LMEM_MOVEABLE option, (vol. 1) 4-285, 4-290 
LMEM_NOCOMPACT option, (vol. 1) 4-285, 4-290 
LMEM_NODISCARD option, (vol. 1) 4-286, 4-291 
LMEM_ZEROINIT option, (vol. 1) 4-286, 4-291 
LoadAccelerators function, (vol. 1) 3-7, 4-275 
LoadBitmap function, (vol. 1) 2-26, 3-7, 4-275 to 4-276 
LoadCursor function, (vol. 1) 1-62, 3-7, 4-277 
LoadIcon function, (vol. 1) 3-7, 4-278 
LoadLibrary function, (vol. 1) 3-2, 4-279 
LoadMenu function, (vol. 1) 3-7, 4-280 
LoadMenulndirect function, (vol. 1) 1-57, 4-281 
LoadModule function, (vol. 1) 3-15, 4-281 to 4-282 
LOADONCALL resource-compiler key word, (vol. 2) 
8-2 to 8-3, 8-5 to 8-6, 8-9, 8-13 
LoadResource function, (vol. 1) 3-7, 4-283 
LoadString function, (vol. 1) 3-7, 4-284, (vol. 2) 8-5 
LOBYTE utility macro, (vol. 1) 3-13, 4-285 
Local heap, (vol. 2) 10-5 
Local stack, (vol. 2) 10-9 
LocalAlloc function, (vol. 1) 3-4, 4-285 
LocalCompact function, (vol. 1) 3-4, 4-286 
LocalDiscard function, (vol. 1) 3-4, 4-287 
LocalFlags function, (vol. 1) 3-4, 4-287 
LocalFree function, (vol. 1) 3-4, 4-288 
LOCALHANDLE data type, (vol. 2) 7-3 
LocalHandle function, (vol. 1) 3-4, 4-288 
LocalInit function, (vol. 1) 3-4, 4-288 
LocalLock function, (vol. 1) 3-4, 4-289 
LocalReAlloc function, (vol. 1) 3-4, 4-290 
LocalShrink function, (vol. 1) 3-4, 4-291 
LocalSize function, (vol. 1) 3-4, 4-292 
LocalUnlock function, (vol. 1) 3-4, 4-292 
localX, Cmacro, (vol. 2) 13-9, 14-11 
LockData function, (vol. 1) 3-4, 4-293 
LockResource function, (vol. 1) 3-7, 4-293 
LockSegment function, (vol. 1) 3-4, 3-6, 4-294 
LOGBRUSH data structure, (vol. 2) 7-39 
LOGFONT data structure, (vol. 2) 7-40 to 7-44 
Logical palette 

See also LOGPALETTE data structure 

and input focus, (vol. 1) 6-95 

changed, (vol. 1) 6-92 

changing entries in, (vol. 1) 4-387 

creating, (vol. 1) 4-55, (vol. 2) 7-45 

finding color in, (vol. 1) 4-192 

index specifier (direct), (vol. 1) 4-327 

index specifier (indirect), (vol. 1) 4-328 

realizing, (vol. 1) 4-343, 6-92 

retrieving entries, (vol. 1) 4-195 

selecting, (vol. 1) 4-361 
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LOGPALETTE data structure, (vol. 1) 4-55, (vol. 2) 
7-45, 7-55 
LOGPEN data structure, (vol. 2) 7-45 to 7-46 
LOGPIXELSX device capability, (vol. 1) 4-167 
LOGPIXELSY device capability, (vol. 1) 4-167 
long data type, (vol. 2) 7-3 
_lopen function, (vol. 1) 3-14, 4-294 to 4-295 
LOWORD utility macro, (vol. 1) 3-13, 4-171, 4-296 
LPBITMAP data type, (vol. 2) 7-3 
LPBITMAPCOREHEADER data type, (vol. 2) 7-3 
LPBITMAPCOREINFO data type, (vol. 2) 7-3 
LPBITMAPFILEHEADER data type, (vol. 2) 7-3 
LPBITMAPINFO data type, (vol. 2) 7-3 
LPBITMAPINFOHEADER data type, (vol. 2) 7-3 
LPCOMPAREITEMSTRUCT data type, (vol. 2) 7-3 
LPCREATESTRUCT data type, (vol. 2) 7-3 
LPDELETEITEMSTRUCT data type, (vol. 2) 7-3 
LPDRAWITEMSTRUCT data type, (vol. 2) 7-3 
LPHANDLETABLE data type, (vol. 2) 7-3 
LPINT data type, (vol. 2) 7-3 
LPLOGBRUSH data type, (vol. 2) 7-3 
LPLOGFONT data type, (vol. 2) 7-3 
LPLOGPALETTE data type, (vol. 2) 7-3 
LPLOGPEN data type, (vol. 2) 7-4 
LPMEASUREITEMSTRUCT data type, (vol. 2) 7-4 
LPMETAFILEPICT data type, (vol. 2) 7-4 
LPMSG data type, (vol. 2) 7-4 
LPOFSTRUCT data type, (vol. 2) 7-4 
LPPAINTSTRUCT data type, (vol. 2) 7-4 
LPPALETTEENTRY data type, (vol. 2) 7-4 
LPPOINT data type, (vol. 2) 7-4 
LPRECT data type, (vol. 2) 7-4 
LPSTR data type, (vol. 2) 7-4 
LPTEXTMETRIC data type, (vol. 2) 7-4 
LPtoDP function, (vol. 1) 2-20, 4-296 
LPVOID data type, (vol. 2) 7-4 
LPWNDCLASS data type, (vol. 2) 7-4 
_lread function, (vol. 1) 3-14, 4-297 
Istrcat function, (vol. 1) 3-8, 4-297 
Istremp function, (vol. 1) 3-8, 4-298 
Istrempi function, (vol. 1) 3-8, 4-299 
Istrcepy function, (vol. 1) 3-9, 4-299 
Istrlen function, (vol. 1) 3-9, 4-300 
LTEXT resource statement 

described, (vol. 2) 8-20 to 8-21 

DIALOG resource statement, (vol. 2) 8-20 
LTGRAY_BRUSH stock object, (vol. 1) 4-207 
_lwrite function, (vol. 1) 3-14, 4-300 to 4-301 


M 


Macro Assembler, (vol. 2) 13-1 
Macros, Cmacro, (vol. 2) 13-6, 14-1 


MAKEINTATOM utility macro, (vol. 1) 3-10, 3-13, 
4-302 
MAKEINTRESOURCE function, (vol. 1) 3-13 
MAKEINTRESOURCE utility macro, (vol. 1) 4-153, 
4-302 
MAKELONG utility macro, (vol. 1) 3-13, 4-302 
MAKEPOINT utility macro, (vol. 1) 3-13, 4-303 
MakeProcInstance function, (vol. 1) 3-2, 4-303, (vol. 2) 
7-1 
MapDialogRect function, (vol. 1) 1-44, 4-304 
Mapping mode, default, (vol. 1) 1-33 
MapVirtualKey function, (vol. 1) 1-31, 4-305 
MARKPARITY parity type, (vol. 2) 7-23 
max macro, (vol. 1) 4-305 
Maximize box, (vol. 2) 8-17 
MB_ABORTRETRYIGNORE option , (vol. 1) 4-308 
MB_APPLMODAL option, (vol. 1) 4-308 
MB_DEFBUTTONI option, (vol. 1) 4-308 
MB_DEFBUTTON2 option, (vol. 1) 4-308 
MB_DEFBUTTON3 option, (vol. 1) 4-308 
MB_ICONASTERISK option, (vol. 1) 4-308 
MB_ICONEXCLAMATION option, (vol. 1) 4-308 
MB_ICONHAND option, (vol. 1) 4-308 
MB_ICONINFORMATION option, (vol. 1) 4-308 
MB_ICONQUESTION option, (vol. 1) 4-308 
MB_ICONSTOP option, (vol. 1) 4-308 
MB_OK option, (vol. 1) 4-308 
MB_OKCANCEL option, (vol. 1) 4-308 
MB_RETRYCANCEL option, (vol. 1) 4-308 
MB_SYSTEMMODAL option, (vol. 1) 4-308 
MB_TASKMODAL option, (vol. 1) 4-309 
MB_YESNO option, (vol. 1) 4-309 
MB_YESNOCANCEL option, (vol. 1) 4-309 
MDI. See Multiple document interface (MDI) 
MDICREATESTRUCT 

as parameter of WM_MDICREATE message, (vol. 1) 
6-76 

data structure, (vol. 2) 7-47 
MEASUREITEMSTRUCT data structure, (vol. 1) 6-80, 
(vol. 2) 7-48 to 7-50 
memC option, Cmacro, (vol. 2) 13-2 
memH option, Cmacro, (vol. 2) 13-2 
memL option, Cmacro, (vol. 2) 13-2 
memM option, Cmacro, (vol. 2) 13-2 
MEMORY combine type, Cmacro, (vol. 2) 14-6 
Memory, least-recently used, (vol. 1) 4-241 to 4-242 
Memory model 

flat, (vol. 2) E-1 

segmented, (vol. 2) E-2 
Memory-model option 

Cmacro, (vol. 2) 13-2 

compact. See memC option, Cmacro 

huge. See memH option, Cmacro 
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large. See memL option, Cmacro 

medium. See memM option, Cmacro 

small. See memS option, Cmacro 
memS option, Cmacro, (vol. 2) 13-2 
Menu 


changing, (vol. 1) 4-11 to 4-13, 4-256 to 4-258, 4-309 to 


4-311 

class, (vol. 1) 1-14 

creating, (vol. 1) 4-54 

deleting, (vol. 1) 4-87 

loading, (vol. 2) 7-50 

owner-draw. See Menu, owner-draw 

pop-up, (vol. 1) 1-26, 4-59 

resource, (vol. 2) 8-8 
Menu bar, described, (vol. 1) 1-25 
Menu checkmark 

custom, (vol. 1) 4-385 

getting size of, (vol. 1) 4-184 
Menu functions, (vol. 1) 1-56 
Menu item, removing, (vol. 1) 4-349 
Menu, owner-draw 

drawing, (vol. 2) 7-36 

measuring, (vol. 2) 7-48 
MENU resource statement, (vol. 2) 8-8 to 8-11, 8-13, 
8-18 
MENUBARBREAK option 

MENUITEM statement, (vol. 2) 8-11 

POPUP statement, (vol. 2) 8-12 
MENUBREAK option 

MENUITEM statement, (vol. 2) 8-11 

POPUP statement, (vol. 2) 8-11 
MENUITEM SEPARATOR statement, (vol. 2) 8-13 
MENUITEM statement, (vol. 2) 8-10 
MENUITEMTEMPLATE data structure, (vol. 2) 7-50 to 
7-51 
MERGECOPY raster operation, (vol. 1) 4-19 
MERGEPAINT raster operation, (vol. 1) 4-19 
Message functions, (vol. 1) 1-2 
MessageBeep function, (vol. 1) 1-59, 4-306 
MessageBox function, (vol. 1) 1-59, 4-306 to 4-308 
Messages 

application queue, (vol. 1) 1-3 

bypassing the queue, (vol. 1) 1-3 

checking the queue, (vol. 1) 1-5 

clipboard, (vol. 1) 5-7 

closing, (vol. 1) 1-28 

contents, (vol. 1) 6-1 

described, (vol. 1) 1-6 

destroy message, (vol. 1) 1-28 

dispatching, (vol. 1) 1-3 

examining 

checking queues, passing, posting, (vol. 1) 1-6 
formatted and transmitting, (vol. 1) 1-6 


generated by applications, (vol. 1) 1-3 
generating or processing 
input events and application queue, (vol. 1) 1-3 
queuing and virtual-key, (vol. 1) 1-3 
input events, (vol. 1) 1-3 
integer, (vol. 1) 6-1 
keyboard input, (vol. 1) 1-4 
peeking, (vol. 1) 1-5 
posting, (vol. 1) 1-5, 4-335 
pulling, (vol. 1) 1-3 
pushing, (vol. 1) 1-3 
ranges, (vol. 1) 6-1 
reading, (vol. 1) 1-3, 1-5 
reserved, (vol. 1) 6-1 
sending, (vol. 1) 1-5 
special actions, (vol. 1) 1-3 
string, (vol. 1) 6-1 
translating 
accelerator keys, (vol. 1) 1-5 
described, (vol. 1) 1-4 
loops, (vol. 1) 1-5 
virtual keys, (vol. 1) 1-4 
window 
default processing, (vol. 1) 4-85 
functions, (vol. 1) 1-3 
Metafile file format, (vol. 2) 9-6 
Metafile functions 
additional escapes, (vol. 1) 2-47 
described, (vol. 1) 2-41 
environment, (vol. 1) 2-47 
information escapes, (vol. 1) 2-47 
printer escapes 
banding, (vol. 1) 2-45 to 2-46 
starting and ending, (vol. 1) 2-46 
terminating, (vol. 1) 2-46 
Metafile picture format, (vol. 2) 7-52 
METAFILEPICT data structure, (vol. 2) 7-52 
Metafiles 
changing, (vol. 1) 2-43 
creating, (vol. 1) 2-41 to 2-42 
deleting, (vol. 1) 2-43 
storing, (vol. 1) 2-43 
MF_BITMAP menu flag, (vol. 1) 4-13, 4-258, 4-311, 
6-81 
MF_BYCOMMAND menu flag, (vol. 1) 4-25, 4-112, 
4-253, 4-258, 4-311 
MF_BYPOSITION menu flag, (vol. 1) 4-25, 4-112, 
4-253, 4-258, 4-311 
MF_CHECKED menu flag, (vol. 1) 4-13, 4-25, 4-186, 
4-258, 4-311, 6-81 
MF_CHECKED mentu-item option, (vol. 2) 7-51 
MF_DISABLED menu flag, (vol. 1) 4-13, 4-112, 4-186, 
4-258, 4-311, 6-81 
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MF_ENABLED menu flag, (vol. 1) 4-13, 4-112, 4-186, 
4-258, 4-311 

MF_END menu option, (vol. 2) 7-51 

MF_GRAYED menu flag, (vol. 1) 4-13, 4-112, 4-186, 
4-258, 4-311, 6-81 

MF_HELP menu-item option, (vol. 2) 7-51 
MF_HILITE menu flag, (vol. 1) 4-253 
MF_MENUBARBREAK ment flag, (vol. 1) 4-13, 
4-186, 4-258, 4-311 

MF_MENUBARBREAK menv-item option, (vol. 2) 7-51 
MF_MENUBREAK menu flag, (vol. 1) 4-13, 4-186, 
4-258, 4-312 

MF_MENUBREAK menv-item option, (vol. 2) 7-51 
MF_MOUSESELECT menu flag, (vol. 1) 6-81 
MF_OWNERDRAW menu flag, (vol. 1) 4-13, 4-259, 
4-312, 6-81 

MF_OWNERDRAW mentu-item option, (vol. 2) 7-51 
MF_POPUP menu flag, (vol. 1) 4-14, 4-259, 4-312, 6-81 
MF_POPUP menv-item option, (vol. 2) 7-51 
MF_SEPARATOR menu flag, (vol. 1) 4-14, 4-186, 
4-259, 4-312 

MF_STRING menu flag, (vol. 1) 4-14, 4-259, 4-312 
MF_SYSMENU menu flag, (vol. 1) 6-81 
MF_UNCHECKED menu flag, (vol. 1) 4-14, 4-25, 
4-186, 4-259, 4-312 

MF_UNHILITE ment flag, (vol. 1) 4-253 
MFCOMMENT printer escape, (vol. 2) 12-38 
MIDCREATESTRUCT menu flag, (vol. 2) 7-48 

min macro, (vol. 1) 4-309 

Minimize box, (vol. 2) 8-17 

Minus (-) sign, (vol. 2) 14-7 

MK_CONTROL mouse-key code, (vol. 1) 6-71 to 6-74, 
6-82, 6-96 to 6-97 

MK_LBUTTON mouse-key code, (vol. 1) 6-71, 6-73 to 
6-74, 6-82, 6-96 to 6-97 

MK_MBUTTON mouse-key code, (vol. 1) 6-71 to 6-73, 
6-82, 6-96 to 6-97 

MK_RBUTTON mouse-key code, (vol. 1) 6-71 to 6-74, 
6-82, 6-96 

MK_SHIFT mouse-key code, (vol. 1) 6-71 to 6-74, 6-82, 
6-96 to 6-97 

MM_ANISOTROPIC mapping mode, (vol. 1) 4-383 
MM_HIENGLISH mapping mode, (vol. 1) 4-383 
MM_HIMETRIC mapping mode, (vol. 1) 4-383 
MM_ISOTROPIC mapping mode, (vol. 1) 4-384 
MM_LOENGLISH mapping mode, (vol. 1) 2-20, 4-384 
MM_LOMETRIC mapping mode, (vol. 1) 4-384 
MM_TEXT mapping mode, (vol. 1) 2-19, 4-384 
MM_TWIPS mapping mode, (vol. 1) 4-384 

Mnemonic, (vol. 2) 8-10, 8-21 to 8-25, 8-27 to 8-29 
ModifyMenu function, (vol. 1) 1-57, 4-211, 4-309 to 
4-311, 6-106 

Module-definition file 


CODE statement, (vol. 2) 10-2 
DATA statement, (vol. 2) 10-2 
DESCRIPTION statement, (vol. 2) 10-3 
EXETYPE statement, (vol. 2) 10-4 
EXPORTS statement, (vol. 2) 10-4 
HEAPSIZE statement, (vol. 2) 10-5 
IMPORTS statement, (vol. 2) 10-6 
LIBRARY statement, (vol. 2) 10-7 
module statement, (vol. 2) 10-1 
NAME statement, (vol. 2) 10-7 
SEGMENTS statement, (vol. 2) 10-8 
STACKSIZE statement, (vol. 2) 10-9 
STUB statement, (vol. 2) 10-10 
Module statement in module-definition file, (vol. 2) 10-1 
Mouse cursor. See Cursor 
MOVEABLE resource-compiler key word, (vol. 2) 8-2, 
8-4 to 8-6, 8-9, 8-14 
MoveTo function, (vol. 1) 2-22, 4-312 
MoveWindow function, (vol. 1) 1-29, 4-313 
MSG data structure, (vol. 2) 7-53 
MSGF_DIALOGBOxX filter-function message type, (vol. 
1) 4-426 to 4-427 
MSGF_MENU filter-function message type, (vol. 1) 
4-426 to 4-427 
MSGF_MESSAGEBOxX filter-function message type, 
(vol. 1) 4-427 
MulDiv function, (vol. 1) 3-13, 4-314 
MULTIKEYHELP data structure, (vol. 2) 7-53 
Multiple document interface (MDI) 
child window, (vol. 2) 7-16 
activating, (vol. 1) 6-75, 6-78 
active, (vol. 1) 6-77 
cascading, (vol. 1) 6-75 
closing, (vol. 1) 6-76 
creating, (vol. 1) 6-75, (vol. 2) 7-47 
default function, (vol. 1) 4-84 
maximizing, (vol. 1) 6-77 
restoring, (vol. 1) 6-78 
system accelerator, (vol. 1) 4-445 
tiling, (vol. 1) 6-79 
client window, (vol. 1) 6-75 to 6-77, 6-79 
described, (vol. 1) 1-25 
frame window default function, (vol. 1) 4-81 
messages, (vol. 1) 5-19 
system accelerator, (vol. 1) 4-445 
Multiple-line edit control, (vol. 2) 8-40 
Multiple-line resource statement 
ACCELERATORS, (vol. 2) 8-7 
DIALOG, (vol. 2) 8-13 
MENU, (vol. 2) 8-8 
RCDATA, (vol. 2) 8-4 
STRINGTABLE, (vol. 2) 8-5 
Multitasking, defined, (vol. 1) xvi 
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N 


NAME module-definition statement, (vol. 2) 10-7 
NAME statement, (vol. 2) 10-1 
Naming 

conventions, data types, (vol. 2) 7-5 

executable module, (vol. 2) 10-7 

imported functions, (vol. 2) 10-6 

library module, (vol. 2) 10-7 
NEAR data type, (vol. 2) 7-4 
NETBIOS interrupt, function request (SCH), (vol. 1) 
4-315 
NetBIOSCall function, (vol. 1) 3-6, 4-315 
NEWFRAME printer escape, (vol. 2) 12-38 
NEXTBAND printer escape, (vol. 2) 12-39 
NOINVERT option, ACCELERATORS resource 
statement, (vol. 2) 8-8 
Non-resident segments, (vol. 2) 14-5 
NOPARITY parity type, (vol. 2) 7-23 
Notification codes 

button, (vol. 1) 5-15 

edit control, (vol. 1) 5-16 
NPSTR data type, (vol. 2) 7-4 
NULL_BRUSH stock object, (vol. 1) 4-207 
NULL_PEN stock object, (vol. 1) 4-207 
NULLREGION region type, (vol. 1) 4-32, 4-129 to 
4-130, 4-158, 4-224, 4-260, 4-318 to 4-319, 4-359 
NUMBRUSHES device capability, (vol. 1) 4-167 
NUMCOLORS device capability, (vol. 1) 4-167 
NUMFONTS device capability, (vol. 1) 4-167 
NUMPENS device capability, (vol. 1) 4-167 


0 


ODA_DRAWENTIRE drawing action, (vol. 2) 7-37 
ODA_FOCUS drawing action, (vol. 2) 7-37 
ODA_SELECT drawing action, (vol. 2) 7-37 
ODDPARITY parity type, (vol. 2) 7-23 
ODS_CHECKED owner-draw control status, (vol. 2) 
7-37 

ODS_DISABLED owner-draw control status, (vol. 2) 
7-37 

ODS_FOCUS owner-draw control status, (vol. 2) 7-37 
ODS_GRAYED owner-draw control status, (vol. 2) 7-37 
ODS_SELECTED owner-draw control status, (vol. 2) 
7-37 

ODT_BUTTON owner-draw control type, (vol. 2) 7-36, 
7-49 

ODT_COMBOBOxX owner-draw control type, (vol. 2) 
7-19, 7-27, 7-36, 7-49 

ODT_LISTBOX owner-draw control type, (vol. 2) 7-19, 
7-27, 7-36, 7-49 

ODT_MENU owner-draw control type, (vol. 2) 7-36, 


7-49 
OEM_FIXED_FONT stock object, (vol. 1) 4-207 
OemKeyScan function, (vol. 1) 1-31, 4-316 
OemToAnsi function, (vol. 1) 3-9, 4-316 
OemToAnsiBuff function, (vol. 1) 3-9, 4-317 
OF_CANCEL option, (vol. 1) 4-323 
OF_CREATE option, (vol. 1) 4-323 
OF_DELETE option, (vol. 1) 4-323 
OF_EXIST option, (vol. 1) 4-323 
OF_PARSE option, (vol. 1) 4-323 
OF_PROMPT option, (vol. 1) 4-323 
OF_READ option, (vol. 1) 4-295, 4-323 
OF_READWRITE option, (vol. 1) 4-295 
OF_REOPEN option, (vol. 1) 4-323 
OF_VERIFY option, (vol. 1) 4-325 
OF_WRITE option, (vol. 1) 4-296, 4-325 
OFFSET macro, Cmacro, (vol. 2) 14-6 
Offset value, (vol. 2) 14-4, 14-6 
OffsetClipRgn function, (vol. 1) 2-22, 4-317 
OffsetRect function, (vol. 1) 1-67 to 1-68, 4-318 
OffsetRgn function, (vol. 1) 2-21, 4-319 
OffsetViewportOrg function, (vol. 1) 2-15, 4-319 
OffsetWindowOrg function, (vol. 1) 2-15, 4-320 
OFSTRUCT data structure, (vol. 2) 7-54 
ONESSTOPBITS stop-bits type, (vol. 2) 7-24 
ONESTOPBIT stop-bits type, (vol. 2) 7-24 
OPAQUE background mode, (vol. 1) 4-365 
OpenClipboard function, (vol. 1) 1-59, 4-321 
OpenComm function, (vol. 1) 3-11, 4-321 
OpenFile function, (vol. 1) 3-14, 4-322 to 4-324 
Openicon function, (vol. 1) 1-29, 4-325 
OpenSound function, (vol. 1) 3-12, 4-326 
Option 

MENUBARBREAK, (vol. 2) 8-11 

MENUBREAK, (vol. 2) 8-11 

SHIFT, (vol. 2) 8-8 
Option, Cmacro 

memcC, (vol. 2) 13-2 

memL, (vol. 2) 13-2 

memM, (vol. 2) 13-2 

memory-model, (vol. 2) 13-2 

memS, (vol. 2) 13-2 

?PLM, (vol. 2) 13-3 

stack-checking, (vol. 2) 13-6 

WIN, (vol. 2) 13-4 
Option, menu-item 

CHECKED, (vol. 2) 8-10, 8-12 

GRAYED, (vol. 2) 8-11 to 8-12 

HELP, (vol. 2) 8-10 

INACTIVE, (vol. 2) 8-10 to 8-11 

MENUBARBREAK, (vol. 2) 8-12 
OR operator, (vol. 2) 8-12, 8-21 to 8-22, 8-24 to 8-27, 
8-30 to 8-32 
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Origin 

brush, default, (vol. 1) 1-33 

viewport, default, (vol. 1) 1-33 

window, default, (vol. 1) 1-34 
OutputDebugString function, (vol. 1) 3-14, 4-326 
Overlapped window, (vol. 1) 1-22 
Overriding types, (vol. 2) 13-9 
Owner-draw button. See Button, owner-draw 
Owner-draw control. See Control, owner-draw 
Owner-draw dialog box controls, (vol. 1) 1-51 
Owner-draw menu. See Menu, owner-draw 
OWNERDRAWEIXED resource option, (vol. 1) 6-80 


P 


PAGE alignment type, (vol. 2) 14-5 
Painting 
functions, (vol. 1) 1-31 
inverting, drawing, filling, (vol. 1) 1-39 
rectangles, (vol. 1) 1-39 
systems display, (vol. 1) 1-31 
updating 
background, (vol. 1) 1-38 
displays, (vol. 1) 1-37 
nonclient area, (vol. 1) 1-42 
validating 
rectangle, (vol. 1) 4-455 
region, (vol. 1) 4-455 
PaintRgn function, (vol. 1) 2-21, 4-327 
PAINTSTRUCT data structure, (vol. 2) 7-55 
Palette, logical. See Logical palette 
Palette, system, retrieving entries, (vol. 1) 4-213 
PALETTEENTRY data structure, (vol. 2) 7-45, 7-55 
PALETTEINDEX utility macro, (vol. 1) 3-13, 4-327 
PALETTERGB utility macro, (vol. 1) 3-13, 4-327 
PARA alignment type, (vol. 2) 14-5 
Parentheses ( ) 
as document convention, (vol. 1) xxiv, (vol. 2) ix 
overriding type, (vol. 2) 13-10 
parmX macro, Cmacro, (vol. 2) 13-9 to 13-10, 14-5 
Pascal calling convention, (vol. 2) 13-3 to 13-4 
PASSTHROUGH printer escape, (vol. 2) 12-40 
PatBlt function, (vol. 1) 2-26, 4-328 
PATCOPY raster operation, (vol. 1) 4-19 
PATINVERT raster operation, (vol. 1) 4-19 
PATPAINT raster operation, (vol. 1) 4-19 
PC_EXPLICIT palette-entry option, (vol. 2) 7-56 
PC_NOCOLLAPSE palette-entry option, (vol. 2) 7-56 
PC_RESERVED palette-entry option, (vol. 1) 4-7, (vol. 
2) 7-56 
PDEVICESIZE device capability, (vol. 1) 4-167 
PeekMessage function, (vol. 1) 1-2, 4-329 to 4-330 
Pen 


creating, (vol. 1) 4-56 to 4-57, (vol. 2) 7-45 

position, default, (vol. 1) 1-33 
Pie function, (vol. 1) 2-24 to 2-25, 4-331 
PINT data type, (vol. 2) 7-4 
PLANES device capability, (vol. 1) 4-167 
PlayMetaFile function, (vol. 1) 2-41, 4-332 
PlayMetaFileRecord function, (vol. 1) 2-41, 4-332 
PLM option 

calling convention, defined, (vol. 2) 13-8 

Cmacro, (vol. 2) 13-3 to 13-4 
Plus (+) operator, (vol. 2) 8-21 to 8-26, 8-28 to 8-33 
Plus (+) sign, with bias value, (vol. 2) 14-7 
PM_NOREMOVE option, (vol. 1) 4-330 
PM_NOYIELD option, (vol. 1) 4-330 
PM_REMOVE option, (vol. 1) 4-330 
POINT data structure, (vol. 1) 4-93, (vol. 2) 7-56 
Pointer naming, Cmacro, (vol. 2) 14-9 
Polygon-filling mode, default, (vol. 1) 1-33 
Polygon function, (vol. 1) 2-24, 4-333 
POLYGONALCAPS device capability, (vol. 1) 4-169 
Polyline function, (vol. 1) 2-22, 4-334 
PolyPolygon function, (vol. 1) 2-24, 4-334 
Pop-up menu 

creating, (vol. 1) 4-59 

described, (vol. 1) 1-26, (vol. 2) 8-11 

nested, (vol. 2) 8-12 
POPUP resource statement, (vol. 2) 8-10 to 8-12 
PostAppMessage function, (vol. 1) 1-2, 4-335 
PostMessage function, (vol. 1) 1-2, 4-335 
PostQuitMessage function, (vol. 1) 1-2, 4-336 
PRELOAD resource-compiler key word, (vol. 2) 8-2 to 
8-4, 8-6, 8-9, 8-13 
Printer-control functions, (vol. 1) 2-44 
Printer device driver 

capabilities, (vol. 1) 4-91 

initialization, (vol. 1) 4-130, (vol. 2) 7-27 
Printer-escape functions 

banding, (vol. 1) 2-45 

creating output, (vol. 1) 2-45 
ProfClear function, (vol. 1) 3-15, 4-337 
ProfFinish function, (vol. 1) 3-15, 4-337 
ProfFlush function, (vol. 1) 3-15, 4-337 
ProfInsChk function, (vol. 1) 3-15, 4-338 
ProfSampRate function, (vol. 1) 3-15, 4-338 
ProfSetup function, (vol. 1) 3-15, 4-338 to 4-339 
ProfStart function, (vol. 1) 3-15, 4-340 
ProfStop function, (vol. 1) 3-15, 4-340 
Programming model, setting, (vol. 2) 13-2 
Prolog 

code, (vol. 2) 13-4 

Windows, (vol. 2) 13-4 
PROOF_QUALITY font quality, (vol. 2) 7-43 
Property list functions, (vol. 1) 1-65 
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adding entries, (vol. 1) 1-67 

creating, (vol. 1) 1-67 

dumping contents, (vol. 1) 1-67 
PSTR data type, (vol. 2) 7-4 
PtInRect function, (vol. 1) 1-67 to 1-68, 4-340 
PtInRegion function, (vol. 1) 2-21, 4-341 
PtVisible function, (vol. 1) 2-22, 4-341 to 4-342 
PUBLIC combine type, Cmacro, (vol. 2) 14-6 
PUBLIC function, Cmacro, (vol. 2) 13-10 
Public labels, (vol. 2) 13-7 
Public variable, (vol. 2) 14-11 
PUSHBUTTON resource statement 

described, (vol. 2) 8-25 

DIALOG resource statement, (vol. 2) 8-20 
PWORD data type, (vol. 2) 7-4 


Q 


QUERYESCSUPPORT printer escape, (vol. 2) 12-41 
Queue 
application, (vol. 1) 1-3 
checking, (vol. 1) 1-5 
Quotation marks (“”’) 
as document convention, (vol. 1) xxv, (vol. 2) x 
in strings, (vol. 2) 8-7, 8-10 


R 


R2_BLACK raster drawing mode, (vol. 2) 11-2 to 11-3 
R2_COPYPEN raster drawing mode, (vol. 2) 11-2 to 11-3 
R2_MASKNOTPEN raster drawing mode, (vol. 1) 
4-395, (vol. 2) 11-2 to 11-3 

R2_MASKPEN raster drawing mode, (vol. 1) 4-395, 
(vol. 2) 11-2 to 11-4 

R2_MASKPENNOT raster drawing mode, (vol. 1) 
4-395, (vol. 2) 11-2 to 11-4 

R2_MERGENOTPEN raster drawing mode, (vol. 1) 
4-395, (vol. 2) 11-2 to 11-4 

R2_MERGEPEN raster drawing mode, (vol. 1) 4-395, 
(vol. 2) 11-2 to 11-4 

R2_MERGEPENNOT raster drawing mode, (vol. 1) 
4-395, (vol. 2) 11-2 to 11-4 

R2_NOP raster drawing mode, (vol. 2) 11-2 to 11-4 
R2_NOT raster drawing mode, (vol. 1) 4-395, (vol. 2) 
11-2 to 11-4 

R2_NOTCOPYPEN raster drawing mode, (vol. 1) 4-395, 
(vol. 2) 11-2 to 11-4 

R2_NOTMASKPEN raster drawing mode, (vol. 1) 
4-395, (vol. 2) 11-2 to 11-4 

R2_NOTMERGEPEN raster drawing mode, (vol. 1) 
4-395, (vol. 2) 11-2 to 11-4 

R2_NOTXORPEN raster drawing mode, (vol. 1) 4-395, 
(vol. 2) 11-2 to 11-4 

R2_WHITE raster drawing mode, (vol. 2) 11-2 to 11-4 


R2_XORPEN raster drawing mode, (vol. 1) 4-395, (vol. 
2) 11-2 to 11-4 
Radio-button control, (vol. 2) 8-29 
RADIOBUTTON resource statement 

described, (vol. 2) 8-29 to 8-30 

DIALOG resource statement, (vol. 2) 8-20 
Raster fonts, digitized aspect, (vol. 1) 2-36 
RASTERCAPS device capability, (vol. 1) 4-168 
Raw-data resource. See RCDATA resource statement 
RC_BANDING device capability, (vol. 1) 4-168 
RC_BITBLT device capability, (vol. 1) 4-168 
RC_BITMAP64 device capability, (vol. 1) 4-168 
RC_DI_BITMAP device capability, (vol. 1) 4-168 
RC diagnostic messages, (vol. 2) B-1 to B-10 
RC_DIBTODEYV device capability, (vol. 1) 4-168 
RC_FLOODFILL device capability, (vol. 1) 4-168 
RC_GDI20_OUTPUT device capability, (vol. 1) 4-168 
RC_PALETTE device capability, (vol. 1) 4-168 
RC_SCALING device capability, (vol. 1) 4-168 
RC_STRETCHBLT device capability, (vol. 1) 4-168 
RC_STRETCHDIB defice capability, (vol. 1) 4-168 
RCDATA resource statement, (vol. 2) 8-4 to 8-5 
ReadComm function, (vol. 1) 3-11, 4-343 
Realize. See Logical palette 
RealizePalette function, (vol. 1) 2-10, 4-343 
RECT data structure, (vol. 2) 7-57 
Rectangle function, (vol. 1) 2-24, 4-344 
Rectangle functions 

additional functions, (vol. 1) 1-67 

coordinates, (vol. 1) 1-67 

in Windows, (vol. 1) 1-67 

InflateRect, (vol. 1) 1-68 

IntersectRect, (vol. 1) 1-68 

IsRectEmpty, (vol. 1) 1-68 

OffsetRect, (vol. 1) 1-68 

PtInRect, (vol. 1) 1-68 

SetRect, (vol. 1) 1-68 

specifying, (vol. 1) 1-67 

UnionRect, (vol. 1) 1-69 
Rectangle, validating, (vol. 1) 4-455 
RectInRegion function, (vol. 1) 2-22, 4-345 
RectVisible function, (vol. 1) 2-22, 4-345 
Region 

rounded rectangle, creating, (vol. 1) 4-60 

validating, (vol. 1) 4-455 
Region functions, (vol. 1) 2-21 
Register 

pointers, (vol. 2) 13-8 

saving, (vol. 2) 14-14 
RegisterClass function, (vol. 1) 1-7, 4-345 
RegisterClipboardFormat function, (vol. 1) 1-59, 4-346 
RegisterWindowMessage function, (vol. 1) 4-347 
Relative-absolute flag, default setting, (vol. 1) 1-33 
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ReleaseCapture function, (vol. 1) 1-30, 4-348 
ReleaseDC function, (vol. 1) 1-32, 4-348 
RemoveFontResource function, (vol. 1) 2-28, 4-348 
RemoveMenu function, (vol. 1) 1-57, 4-349 
RemoveProp function, (vol. 1) 1-65, 4-350 
ReplyMessage function, (vol. 1) 1-2, 4-351 
Reserved messages, (vol. 1) 6-1 
RESETDEV communication function code, (vol. 1) 4-128 
Resource 
bitmap, (vol. 2) 8-2 
cursor, (vol. 2) 8-2 
font, (vol. 2) 8-2 
icon, (vol. 2) 8-2 
loading, (vol. 2) 8-2 to 8-4, 8-6, 8-13 
managing hooks, (vol. 1) 1-63 
raw data, (vol. 2) 8-4 
string, (vol. 2) 8-5 
user-defined, (vol. 2) 8-3 
Resource directive 
#define, (vol. 2) 8-48 
described, (vol. 2) 8-47 
#elif, (vol. 2) 8-50 
#else, (vol. 2) 8-50 
#endif, (vol. 2) 8-51 
#if, (vol. 2) 8-49 
#ifdef, (vol. 2) 8-48 
#ifndef, (vol. 2) 8-49 
#include, (vol. 2) 8-47 
#undef, (vol. 2) 8-48 
Resource statement 
ACCELERATORS 
CONTROL option, (vol. 2) 8-8 
NOINVERT option, (vol. 2) 8-8 
SHIFT option, (vol. 2) 8-8 
DIALOG 
CAPTION statement, (vol. 2) 8-18 
CHECKBOX statement, (vol. 2) 8-23 
CLASS statement, (vol. 2) 8-19 
COMBOBOxX statement, (vol. 2) 8-31 
CONTROL statement, (vol. 2) 8-34 
CTEXT statement, (vol. 2) 8-22 
DEFPUSHBUTTON statement, (vol. 2) 8-28 
described, (vol. 2) 8-13 
dialog control statements, (vol. 2) 8-20 
dialog option statements, (vol. 2) 8-15 
EDITTEXT statement, (vol. 2) 8-30 
FONT statement, (vol. 2) 8-19 
GROUPBOXxX statement, (vol. 2) 8-27 
ICON statement, (vol. 2) 8-33 
LISTBOX< statement, (vol. 2) 8-26 
LTEXT statement, (vol. 2) 8-20 
MENU statement, (vol. 2) 8-18 
options, (vol. 2) 8-13 


PUSHBUTTON statement, (vol. 2) 8-25 
RADIOBUTTON statement, (vol. 2) 8-29 
RTEXT statement, (vol. 2) 8-21 
SCROLLBAR statement, (vol. 2) 8-33 
STYLE statement, (vol. 2) 8-15 
MENU, (vol. 2) 8-8 to 8-11, 8-13 
RCDATA, (vol. 2) 8-4 to 8-5 
resource, (vol. 2) 8-1 
single-line, (vol. 2) 8-1 to 8-2 
STRINGTABLE, (vol. 2) 8-5 to 8-6 
user-defined, (vol. 2) 8-3 to 8-4 
RESTORE_CTM printer escape, (vol. 2) 12-41 
RestoreDC function, (vol. 1) 2-2, 4-352 
RGB 
See also Color 
explicit, (vol. 2) 7-17 
palette-relative, (vol. 2) 7-17 
RGB utility macro, (vol. 1) 3-13, 4-352 
RGBQUAD data structure, (vol. 2) 7-11, 7-58 
RGBTRIPLE data structure, (vol. 2) 7-8, 7-58 
RGN_AND region-combining mode, (vol. 1) 4-31 
RGN_COPY region-combining mode, (vol. 1) 4-31 
RGN_DIFF region-combining mode, (vol. 1) 4-31 
RGN_OR region-combining mode, (vol. 1) 4-31 
RGN_XOR region-combining mode, (vol. 1) 4-31 
RoundRect function, (vol. 1) 2-24, 4-353 to 4-354 
RT_ACCELERATOR resource type, (vol. 1) 4-139 
RT_BITMAP resource type, (vol. 1) 4-139 
RT_DIALOG resource type, (vol. 1) 4-139 
RT_FONT resource type 
RT_MENU resource type, (vol. 1) 4-139 
RT_RCDATA resource type, (vol. 1) 4-139 
RTEXT resource statement, (vol. 2) 8-21 to 8-22 


S 


S_ALLTHRESHOLD voice-queue state, (vol. 1) 4-457 
S_LEGATO voice note style, (vol. 1) 4-410 
S_NORMAL voice note style, (vol. 1) 4-410 
S_PERIODS512 voice frequency, (vol. 1) 4-398 
S_PERIOD1024 voice frequency, (vol. 1) 4-398 
S_PERIOD2048 voice frequency, (vol. 1) 4-398 
S_PERIODVOICE voice frequency, (vol. 1) 4-398 
S_QUEUEEMPTY voice-queue state, (vol. 1) 4-457 
S_SERDCC voice error code, (vol. 1) 4-412 
S_SERDDR voice error code, (vol. 1) 4-414 
S_SERDFQ voice error code, (vol. 1) 4-414 
S_SERDLN voice error code, (vol. 1) 4-412 
S_SERDMD voice error code, (vol. 1) 4-411 
S_SERDNT voice error code, (vol. 1) 4-412 
S_SERDRC voice error code, (vol. 1) 4-412 
S_SERDSH voice error code, (vol. 1) 4-412 
S_SERDTP voice error code, (vol. 1) 4-411 
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S_SERDVL voice error code, (vol. 1) 4-411, 4-414 
S_SERMACT voice error code, (vol. 1) 4-413 
S_SEROFM voice error code, (vol. 1) 4-413 
S_SERQFUL voice error code, (vol. 1) 4-411 to 4-412, 
4-414 

S_STACCATO voice note style, (vol. 1) 4-410 
S_THRESHOLD voice-queue state, (vol. 1) 4-457 
S_WHITES 12 voice frequency, (vol. 1) 4-398 
S_WHITE1024 voice frequency, (vol. 1) 4-398 
S_WHITE2048 voice frequency, (vol. 1) 4-398 
S_WHITEVOICE voice frequency, (vol. 1) 4-398 
SAVE_CTM printer escape, (vol. 2) 12-42 

Save macro, Cmacro, (vol. 2) 14-14 

SaveDC function, (vol. 1) 2-2, 4-355 

Saving, registers, (vol. 2) 14-14 

SB_BOTH scroll-bar type, (vol. 1) 4-431 

SB_BOTTOM scrolling request, (vol. 1) 6-65 to 6-66, 
6-112 to 6-113 

SB_CTL scroll-bar type, (vol. 1) 4-205 to 4-206, 4-396 to 
4-397, 4-431 

SB_ENDSCROLL scrolling request, (vol. 1) 6-65 to 
6-66, 6-112 to 6-113 

SB_HORZ scroll-bar type, (vol. 1) 4-205 to 4-206, 4-396 
to 4-397, 4-431 

SB_LINEDOWN scrolling request, (vol. 1) 6-65 to 6-66, 
6-112 to 6-113 

SB_LINEUP scrolling request, (vol. 1) 6-65 to 6-66, 
6-112 to 6-113 

SB_PAGEDOWN scrolling request, (vol. 1) 6-65 to 
6-66, 6-112 to 6-113 

SB_PAGEUP scrolling request, (vol. 1) 6-65 to 6-66, 
6-112 to 6-113 

SB_THUMBPOSITION scrolling request, (vol. 1) 6-65 
to 6-66, 6-112 to 6-113 

SB_THUMBTRACK scrolling request, (vol. 1) 6-65, 
6-112 

SB_TOP scrolling request, (vol. 1) 6-65 to 6-66, 6-112 to 
6-113 

SB_VERT scroll-bar type, (vol. 1) 4-205 to 4-206, 4-396 
to 4-397, 4-431 

sBegin macro, Cmacro, (vol. 2) 14-5, 14-14 
SBS_BOTTOMALIGN control style, (vol. 1) 4-73, (vol. 
2) 8-44 

SBS_HORZ control style, (vol. 1) 4-73, (vol. 2) 8-44 
SBS_LEFTALIGN control style, (vol. 1) 4-73, (vol. 2) 
8-43 

SBS_RIGHTALIGN control style, (vol. 1) 4-73, (vol. 2) 
8-43 

SBS_SIZEBOX control style, (vol. 1) 4-73, (vol. 2) 8-44 
SBS_SIZEBOXBOTTOMRIGHTALIGN control style, 
(vol. 1) 4-73, (vol. 2) 8-44 
SBS_SIZEBOXTOPLEFTALIGN control style, (vol. 1) 
4-74, (vol. 2) 8-44 


SBS_TOPALIGN control style, (vol. 1) 4-74, (vol. 2) 
8-44 
SBS_VERT control style, (vol. 1) 4-74, (vol. 2) 8-43 
SC_CLOSE system command, (vol. 1) 6-105 
SC_HSCROLL system command, (vol. 1) 6-105 
SC_KEYMENU system command, (vol. 1) 6-105 
SC_MAXIMIZE system command, (vol. 1) 6-105 
SC_MINIMIZE system command, (vol. 1) 6-105 
SC_MOUSEMENU system comman4d, (vol. 1) 6-105 
SC_MOVE system command, (vol. 1) 6-106 
SC_NEXTWINDOW system command, (vol. 1) 6-106 
SC_PREVWINDOW system command, (vol. 1) 6-106 
SC_RESTORE system command, (vol. 1) 6-106 
SC_SIZE system command, (vol. 1) 6-106 
SC_VSCROLL system command, (vol. 1) 6-106 
Scale ViewportExt function, (vol. 1) 2-15, 4-355 
ScaleWindowExt function, (vol. 1) 2-15, 4-356 
ScreenToClient function, (vol. 1) 2-20, 4-356 
Scroll bar 
control-class styles, (vol. 2) 8-41, 8-43 
described, (vol. 1) 1-25 
horizontal, (vol. 2) 8-17 
vertical, (vol. 2) 8-18 
SCROLLBAR control class 
control styles, (vol. 2) 8-43 
described, (vol. 1) 4-65, (vol. 2) 8-36 
SCROLLBAR resource statement, (vol. 2) 8-33 
ScrollIDC function, (vol. 1) 1-53, 4-357 
Scrolling 
described, (vol. 1) 1-55 
functions 
controlling, (vol. 1) 1-54 
described, (vol. 1) 1-53 
processing, (vol. 1) 1-55 
requests, (vol. 1) 1-55 
hiding, (vol. 1) 1-56 
using thumb, (vol. 1) 1-54 
ScrollWindow function, (vol. 1) 1-53, 4-358 
Segment 
alignment type, (vol. 2) 14-6 
class name, (vol. 2) 14-6 
combine type, (vol. 2) 14-6 
Segment macros, Cmacro, (vol. 2) 13-6 
Segment types, mixed, (vol. 2) E-5 to E-6 
Segmented memory mode, (vol. 2) E-2 
SEGMENTS module-definition statement, (vol. 2) 10-8 
SEGMENTS statement, (vol. 2) 10-1 
segNameOFFSET macro, Cmacro, (vol. 2) 14-14 
SelectClipRgn function, (vol. 1) 2-22, 4-359 
SelectObject function, (vol. 1) 2-6, 4-360 
SelectPalette function, (vol. 1) 2-10, 4-361 
SELECTPAPERSOURCE printer escape. See 
GETSETPAPERBINS printer escape 
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sEnd macro, Cmacro, (vol. 2) 14-5, 14-15 
SendDlgItemMessage function, (vol. 1) 1-44, 4-362 
SendMessage function 

described, (vol. 1) 1-2 to 1-3, 4-362 

message deadlock caused by, (vol. 1) 1-6 
SET_ARC_DIRECTION printer escape, (vol. 2) 12-45 
SET_BACKGROUND_COLOR printer escape, (vol. 2) 
12-46 
SET_BOUNDS printer escape, (vol. 2) 12-47 
SET_POLY_MODE printer escape, (vol. 2) 12-53 to 
12-54 
SET_SCREEN_ANGLE printer escape, (vol. 2) 12-55 
SET_SPREAD printer escape, (vol. 2) 12-56 
SETABORTPROC printer escape, (vol. 2) 12-43 
SetActiveWindow function, (vol. 1) 1-30, 4-363 
SETALLJUSTVALUES printer escape, (vol. 2) 12-44 
SetBitmapBits function, (vol. 1) 2-26, 4-363 
SetBitmapDimension function, (vol. 1) 2-26, 4-364 
SetBkColor function, (vol. 1) 2-14, 4-364 
SetBkMode function, (vol. 1) 2-14, 4-365 
SetBrushOrg function, (vol. 1) 2-6, 4-365 
SetCapture function, (vol. 1) 1-30, 4-366 
SetCaretBlinkTime function, (vol. 1) 1-60, 4-366 
SetCaretPos function, (vol. 1) 1-60, 4-367 
SetClassLong function, (vol. 1) 1-8, 1-16, 4-367 
SetClassWord function, (vol. 1) 1-8, 4-368 
SetClipboardData function, (vol. 1) 1-59, 4-369 to 4-371 
SetClipboardViewer function, (vol. 1) 1-59, 4-372 
SETCOLORTABLE printer escape, (vol. 2) 12-48 
SetCommBreak function, (vol. 1) 3-11, 4-372 
SetCommEventMask function, (vol. 1) 3-11, 4-373 
SetCommState function, (vol. 1) 3-11, 4-374 
SETCOPYCOUNT printer escape, (vol. 2) 12-49 
SetCursor function, (vol. 1) 1-62, 4-374 
SetCursorPos function, (vol. 1) 1-62, 4-375 
SetDIBits function, (vol. 1) 2-13, 2-26, 4-168, 4-375 to 
4-376 
SetDIBitsToDevice function, (vol. 1) 2-26, 4-168, 4-377 
to 4-378 
SetDlgItemInt function, (vol. 1) 1-44, 4-378 
SetDlgItemText function, (vol. 1) 1-44, 4-379 
SetDoubleClickTime function, (vol. 1) 1-30, 4-379 
SETDTR communication function code, (vol. 1) 4-128 
SETENDCAP printer escape. See SETLINECAP printer 
escape 
SetEnvironment function, (vol. 1) 2-47, 4-380 
SetErrorMode function, (vol. 1) 3-7, 4-380 
SetFocus function, (vol. 1) 1-30, 4-381 
SetHandleCount function, (vol. 1) 3-14, 4-382 
SETKERNTRACK printer escape, (vol. 2) 12-50 
SetKeyboardState function, (vol. 1) 1-31, 4-382 
SETLINECAP printer escape, (vol. 2) 12-51 
SETLINEJOIN printer escape, (vol. 2) 12-52 


SetMapMode function, (vol. 1) 2-15, 4-383 
SetMapperFlags function, (vol. 1) 2-28, 2-36, 4-384 
SetMenu function, (vol. 1) 1-57, 4-385 
SetMenultemBitmaps function, (vol. 1) 1-57, 4-14, 
4-184, 4-385 

SetMessageQueue function, (vol. 1) 1-2, 4-386 
SetMetaFileBits function, (vol. 1) 2-41, 4-387 
SETMITERLIMIT printer escape, (vol. 2) 12-53 
SetPaletteEntries function, (vol. 1) 2-10, 4-387 
SetParent function, (vol. 1) 1-58, 4-388 

SetPixel function, (vol. 1) 2-26, 4-388 
SetPolyFillMode function, (vol. 1) 2-14, 4-333 to 4-334, 
4-389 

SetProp function, (vol. 1) 1-65, 4-390 

SetRect function, (vol. 1) 1-68, 4-390 

SetRectEmpty function, (vol. 1) 1-67, 4-391 
SetRectRgn function, (vol. 1) 2-22, 4-391 
SetResourceHandler function, (vol. 1) 3-8, 4-392 to 4-393 
SetROP2 function, (vol. 1) 2-14, 4-394 to 4-395 
SETRTS communication function code, (vol. 1) 4-128 
SetScrollPos function, (vol. 1) 1-53, 4-396 
SetScrollRange function, (vol. 1) 1-53, 4-397 
SetSoundNoise function, (vol. 1) 3-12, 4-398 
SetStretchBltMode function, (vol. 1) 2-14, 4-398 
SetSwapAreaSize function, (vol. 1) 3-4, 4-399 
SetSysColors function, (vol. 1) 1-58, 4-400 
SetSysModal Window function, (vol. 1) 1-30, 4-401 
SetSystemPaletteUse function, (vol. 1) 2-10, 4-214, 4-402 
SetTextAlign function, (vol. 1) 2-27, 4-403 to 4-404 
SetTextCharacterExtra function, (vol. 1) 4-405 
SetTextColor function, (vol. 1) 2-14, 4-250, 4-405 
SetTextJustification function, (vol. 1) 2-27, 4-406 
SetTimer function, (vol. 1) 1-30, 4-407 
SetViewportExt function, (vol. 1) 2-15, 4-408 
SetViewportOrg function, (vol. 1) 2-15, 4-409 
SetVoiceAccent function, (vol. 1) 3-12, 4-410 
SetVoiceEnvelope function, (vol. 1) 3-12, 4-411 
SetVoiceNote function, (vol. 1) 3-12, 4-412 
SetVoiceQueueSize function, (vol. 1) 3-12, 4-413 
SetVoiceSound function, (vol. 1) 3-12, 4-413 
SetVoiceThreshold function, (vol. 1) 3-12, 4-414 
SetWindowExt function, (vol. 1) 2-15, 4-414 
SetWindowLong function, (vol. 1) 1-8, 1-16, 4-415 
SetWindowOrg function, (vol. 1) 2-15, 4-416 
SetWindowPos function, (vol. 1) 1-29, 4-417 to 4-418 
SetWindowsHook function, (vol. 1) 1-64, 4-419 to 4-426 
SetWindowText function, (vol. 1) 1-25, 1-29, 4-427 
SetWindow Word function, (vol. 1) 1-8, 4-428 
SETXOFF communication function code, (vol. 1) 4-128 
SETXON communication function code, (vol. 1) 4-128 
SHIFT option, ACCELERATORS resource statement, 
(vol. 2) 8-8 

short data type, (vol. 2) 7-4 
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ShowCaret function, (vol. 1) 1-60, 4-429 

ShowCursor function, (vol. 1) 1-62, 4-429 
ShowOwnedPopups function, (vol. 1) 1-29, 4-430 
ShowScrollBar function, (vol. 1) 1-53, 4-430 

Show Window function, (vol. 1) 1-29, 4-282, 4-431, 4-459 
SIMPLEREGION region type, (vol. 1) 4-32, 4-129 to 
4-130, 4-158, 4-224, 4-260, 4-318 to 4-319, 4-359 
Single-line resource statement, (vol. 2) 8-1 to 8-2 
Size-box control, (vol. 2) 8-17, 8-36 
SIZEFULLSCREEN window-sizing request, (vol. 1) 
6-102 

SIZEICONIC window-sizing request, (vol. 1) 6-102 
SIZENORMAL window-sizing request, (vol. 1) 6-102 
SizeofResource function, (vol. 1) 3-8, 4-432 
SIZEZOOMHIDE window-sizing request, (vol. 1) 6-102 
SIZEZOOMSHOW window-sizing request, (vol. 1) 6-102 
SM_CXBORDER system-metric value, (vol. 1) 4-212 
SM_CXDLGFRAME system-metric value, (vol. 1) 4-212 
SM_CXFRAME system-metric value, (vol. 1) 4-212 
SM_CXFULLSCREEN system-metric value, (vol. 1) 
4-213 

SM_CXHSCROLL system-metric value, (vol. 1) 4-212 
SM_CXHTHUMB system-metric value, (vol. 1) 4-212 
SM_CXMINTRACK system-metric value, (vol. 1) 4-213 
SM_CXSIZE system-metric value, (vol. 1) 4-213 
SM_CXVSCROLL system-metric value, (vol. 1) 4-212 
SM_CYBORDER system-metric value, (vol. 1) 4-212 
SM_CYDLGFRAME system-metric value, (vol. 1) 4-212 
SM_CYFRAME system-metric value, (vol. 1) 4-212 
SM_CYFULLSCREEN system-metric value, (vol. 1) 
4-213 

SM_CYHSCROLL system-metric value, (vol. 1) 4-212 
SM_CYSIZE system-metric value, (vol. 1) 4-213 
SM_CYVSCROLL system-metric value, (vol. 1) 4-212 
SM_CYVTHUMB system-metric value, (vol. 1) 4-212 
SM_DEBUG system-metric value, (vol. 1) 4-213 
SM_MOUSEPRESENT system-metric value, (vol. 1) 
4-213 

SM_SWAPBUTTON system-metric value, (vol. 1) 4-213 
Small capital letters, as document convention, (vol. 1) 
XXvV, (vol. 2) x 

SP_APPABORT escape error code, (vol. 2) 12-38 to 
12-39 

SP_ERROR escape error code, (vol. 1) 4-127, (vol. 2) 
12-38 to 12-39 

SP_OUTOFDISK escape error code, (vol. 1) 4-127, (vol. 
2) 12-39 to 12-40 

SP_OUTOFMEMORY escape error code, (vol. 1) 4-127, 
(vol. 2) 12-39 to 12-40 

SP_USERABORT escape error code, (vol. 1) 4-127, 
(vol. 2) 12-39 to 12-40 

SPACEPARITY parity type, (vol. 2) 7-24 
Special-definition macros, Cmacro, (vol. 2) 13-8 


SRCAND raster operation, (vol. 1) 4-19 
SRCCOPY raster operation, (vol. 1) 4-19 
SRCERASE raster operation, (vol. 1) 4-19 
SRCINVERT raster operation, (vol. 1) 4-19 
SRCPAINT raster operation, (vol. 1) 4-19 
SS_BLACKFRAME control style, (vol. 1) 4-74, (vol. 2) 
8-46 
SS_BLACKRECT control style, (vol. 1) 4-74, (vol. 2) 
8-46 
SS_CENTER control style, (vol. 1) 4-74, (vol. 2) 8-45 
SS_GRAYFRAME control style, (vol. 1) 4-74, (vol. 2) 
8-47 
SS_GRAYRECT control style, (vol. 1) 4-74, (vol. 2) 8-46 
SS_ICON control style, (vol. 1) 4-74, (vol. 2) 8-33, 8-46 
SS_LEFT control style, (vol. 1) 4-75, (vol. 2) 8-45 
SS_LEFTNOWORDWRAP control style, (vol. 1) 4-75, 
(vol. 2) 8-45 
SS_NOPREFIX control style, (vol. 1) 4-75, (vol. 2) 8-46 
SS_RIGHT control style, (vol. 1) 4-75, (vol. 2) 8-45 
SS_SIMPLE control style, (vol. 1) 4-75, (vol. 2) 8-45 
SS_USERITEM control style, (vol. 1) 4-75, (vol. 2) 8-47 
SS_WHITEFRAME control style, (vol. 1) 4-75, (vol. 2) 
8-47 
SS_WHITERECT control style, (vol. 1) 4-75, (vol. 2) 
8-46 
Stack 
local, (vol. 2) 10-9 
mixed segment types, (vol. 2) E-5 to E-6 
Stack-checking option, Cmacro, (vol. 2) 13-6 
STACK combine type, Cmacro, (vol. 2) 14-6 
STACKSIZE module-definition statement, (vol. 2) 10-1, 
10-9 
Standard C calling convention, (vol. 2) 13-3 
STARTDOC printer escape, (vol. 2) 12-57 
StartSound function, (vol. 1) 3-12, 4-433 
Statement 
See also specific statement 
module-definition file 
EXETYPE, (vol. 2) 10-4 
LIBRARY, (vol. 2) 10-7 
NAME, (vol. 2) 10-7 
STATIC control class, (vol. 1) 4-65, (vol. 2) 8-36 
Static-memory storage 
macros, (vol. 2) 13-7 
private, (vol. 2) 14-15 
public, (vol. 2) 14-10 
staticX macro, Cmacro, (vol. 2) 14-15 
StopSound function, (vol. 1) 3-12, 4-433 
Storage 
static-memory, private, (vol. 2) 14-15 
static-memory, public, (vol. 2) 14-10 
Storage-allocation macros, Cmacro, (vol. 2) 13-7 
Storage size, (vol. 2) 14-9 to 14-13, 14-15 


StretchBlt function 
and color palettes, (vol. 1) 2-13 
described, (vol. 1) 2-26, 4-433 to 4-434 
StretchDIBits function, (vol. 1) 2-27, 4-435 to 4-436 
Stretching mode, default, (vol. 1) 1-33 
String messages, (vol. 1) 6-1 
String resource 
See also RCDATA resource statement; STRINGTABLE 
resource statement 
described, (vol. 2) 8-5 
Strings 
comparing, (vol. 1) 4-298 to 4-299 
concatenating, (vol. 1) 4-297 
copying, (vol. 1) 4-299 
determining length of, (vol. 1) 4-300 
formatting, (vol. 1) 4-465, 4-467 
STRINGTABLE resource statement, (vol. 2) 8-5 to 8-6 
STUB module-definition statement, (vol. 2) 10-1, 10-10 
Style, control 
BUTTON class, (vol. 2) 8-24 to 8-25, 8-27, 8-29 to 8-30 
COMBOBOX class, (vol. 2) 8-32 
default 
CHECKBOxX< statement, (vol. 2) 8-24 
COMBOBOX statement, (vol. 2) 8-32 
CTEXT statement, (vol. 2) 8-23 
DEFPUSHBUTTON statement, (vol. 2) 8-29 
EDITTEXT statement, (vol. 2) 8-31 
GROUPBOxX statement, (vol. 2) 8-28 
ICON statement, (vol. 2) 8-33 
LISTBOX statement, (vol. 2) 8-26 
LTEXT statement, (vol. 2) 8-21 
PUSHBUTTON statement, (vol. 2) 8-25 
RADIOBUTTON statement, (vol. 2) 8-30 
RTEXT statement, (vol. 2) 8-22 
DS_ABSALIGN, (vol. 2) 8-14 to 8-15 
EDIT class, (vol. 2) 8-31 
LISTBOX< class, (vol. 2) 8-26 
STATIC class, (vol. 2) 8-33 
STYLE resource statement 
DIALOG resource statement, (vol. 2) 8-14 to 8-15 
listing window style, (vol. 2) 8-15 
when #include directive required with, (vol. 2) 8-15 
Style, window 
listing, (vol. 2) 8-15 
WS_BORDER, (vol. 2) 8-16, 8-26 
WS_CAPTION, (vol. 2) 8-16 
WS_CHILD, (vol. 2) 8-14, 8-16 
WS_CHILDWINDOW, (vol. 2) 8-16 
WS_CLIPCHILDREN, (vol. 2) 8-16 
WS_CLIPSIBLINGS, (vol. 2) 8-16 
WS_DISABLED, (vol. 2) 8-16, 8-25, 8-27, 8-29 to 8-31 
WS_DLGFRAME, (vol. 2) 8-16 
WS_GROUP, (vol. 2) 8-17, 8-21 to 8-25, 8-29 to 8-31 
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WS_HSCROLL, (vol. 2) 8-17, 8-31 

WS_ICONIC, (vol. 2) 8-17 

WS_MAXIMIZE, (vol. 2) 8-17 

WS_MAXIMIZEBOX, (vol. 2) 8-17 

WS_MINIMIZE, (vol. 2) 8-17 

WS_MINIMIZEBOX, (vol. 2) 8-17. 

WS_OVERLAPPED, (vol. 2) 8-17 

WS_OVERLAPPEDWINDOW, (vol. 2) 8-17 

WS_POPUP, (vol. 2) 8-17 

WS_POPUPWINDOW, (vol. 2) 8-17 

WS_SIZEBOX, (vol. 2) 8-17 

WS_SYSMENU, (vol. 2) 8-17 

WS_TABSTOP, (vol. 2) 8-17, 8-21 to 8-25, 8-27, 8-29 to 
8-31 

WS_THICKFRAME, (vol. 2) 8-18 

WS_VISIBLE, (vol. 2) 8-18 

WS_VSCROLL, (vol. 2) 8-18, 8-26, 8-31 
Styles 

dialog box controls, (vol. 1) 1-48 

formatted text, (vol. 1) 1-41 
Subclassing windows, (vol. 1) 1-16, 4-368, 4-416 
SW_HIDE window state, (vol. 1) 4-432 
SW_MINIMIZE window state, (vol. 1) 4-432 
SW_PARENTCLOSING window state, (vol. 1) 6-101 
SW_PARENTOPENING window state, (vol. 1) 6-101 
SW_RESTORE window state, (vol. 1) 4-432 
SW_SHOW window state, (vol. 1) 4-432 
SW_SHOWMAXIMIZED window state, (vol. 1) 4-432 
SW_SHOWMINIMIZED window state, (vol. 1) 4-432 
SW_SHOWMINNOACTIVE window state, (vol. 1) 
4-432 
SW_SHOWNA window state, (vol. 1) 4-432 
SW_SHOWNOACTIVATE window state, (vol. 1) 4-432 
SW_SHOWNORMAL window state, (vol. 1) 4-432 
SwapMouseButton function, (vol. 1) 1-30, 4-437 
SwapRecording function, (vol. 1) 3-15, 4-438 
SwitchStackBack function, (vol. 1) 3-5, 4-438 
SwitchStackTo function, (vol. 1) 3-5, 4-438 
SWP_DRAWFRAME window-position flag, (vol. 1) 
4-80, 4-418 
SWP_HIDEWINDOW window-position flag, (vol. 1) 
4-80, 4-418 
SWP_NOACTIVATE window-position flag, (vol. 1) 
4-80, 4-418 
SWP_NOMOVE window-position flag, (vol. 1) 4-80, 
4-418 
SWP_NOREDRAW window-position flag, (vol. 1) 4-80, 
4-418 
SWP_NOSIZE window-position flag, (vol. 1) 4-80, 4-418 
SWP_NOZORDER window-position flag, (vol. 1) 4-80, 
4-418 
SWP_SHOWWINDOW window-position flag, (vol. 1) 
4-80, 4-418 
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Symbol redefinition, Cmacro, (vol. 2) 13-10 

SyncAll Voices function, (vol. 1) 3-12, 4-439 

System accelerator (MDI), (vol. 1) 4-445 
SYSTEM_FIXED_FONT stock object, (vol. 1) 4-208 
SYSTEM_FONT stock object, (vol. 1) 4-207 

System functions, (vol. 1) 1-58 

System-menu box, (vol. 1) 1-25, (vol. 2) 8-17 
System palette, retrieving entries, (vol. 1) 4-213 
System services interface, defined, (vol. 1) xix 


r 


TA_BASELINE text-alignment flag, (vol. 1) 4-218, 4-404 


TA_BOTTOM text-alignment flag, (vol. 1) 4-218, 4-404 
TA_CENTER text-alignment flag, (vol. 1) 4-218, 4-404 
TA_LEFT text-alignment flag, (vol. 1) 4-218, 4-194 
TA_NOUPDATECP text-alignment flag, (vol. 1) 4-218, 
4-404 
TA_RIGHT text-alignment flag, (vol. 1) 4-218, 4-404 
TA_TOP text-alignment flag, (vol. 1) 4-218, 4-404 
TA_UPDATECP text-alignment flag, (vol. 1) 4-218, 
4-404 
Tab stop, (vol. 2) 8-36 
TabbedTextOut function, (vol. 1) 2-28, 4-440 
Table, handle, (vol. 2) 7-38 
Task 

handle, obtaining, (vol. 1) 4-164 

yielding control, (vol. 1) 1-3, 4-469 
Task windows 

enumerating, (vol. 1) 4-123 

posting messages to, (vol. 1) 4-335 
TECHNOLOGY device capability, (vol. 1) 4-167 
Template, DIALOG, (vol. 2) 8-13 » 
Text 

color, default, (vol. 1) 1-33 

drawing, (vol. 1) 1-42 

graying, (vol. 1) 1-41 
Text control 

left-justified, (vol. 2) 8-20 

right-justified, (vol. 2) 8-21 
Text functions, (vol. 1) 2-27 
TEXTCAPS device capability, (vol. 1) 4-169 
TEXTMETRIC data structure, (vol. 2) 7-59 to 7-61 
TextOut function, (vol. 1) 2-28, 4-441 
Throw function, (vol. 1) 3-7, 4-441 
Timer, killing, (vol. 1) 4-270 
Title bar, (vol. 1) 1-25, (vol. 2) 8-16 to 8-17 
ToAscii function, (vol. 1) 3-9, 4-442 
TrackPopupMenu function, (vol. 1) 1-26, 1-57, 4-59, 
4-443 
TRANSFORM_CTM printer escape, (vol. 2) 12-58 
TranslateAccelerator function, (vol. 1) 1-2, 1-4, 4-444, 
(vol. 2) 8-7 


TranslateMDISysAccel function, (vol. 1) 1-2, 4-445 
TranslateMessage function, (vol. 1) 1-2, 1-4, 4-446 
TransmitCommChar function, (vol. 1) 3-11, 4-446 to 
4-447 

TRANSPARENT background mode, (vol. 1) 4-365 
TWOSTOPBITS stop-bits type, (vol. 2) 7-24 

Types, data, (vol. 2) 7-1 to 7-5 


U 


#undef directive, resource compiler, (vol. 2) 8-48 
ngetCommChar function, (vol. 1) 3-11, 4-448 
nhookWindowsHook function, (vol. 1) 1-64, 4-448 
nionRect function, (vol. 1) 1-67, 1-69, 4-449 
nlockData function, (vol. 1) 3-5, 4-449 
nlockResource function, (vol. 1) 3-8, 4-450 
nLockSegment function, (vol. 1) 3-5 to 3-6, 4-450 
nrealizeObject function, (vol. 1) 2-6, 4-451 
nregisterClass function, (vol. 1) 1-8, 4-452 
pdateColors function, (vol. 1) 2-10, 4-452 
pdateWindow function, (vol. 1) 1-32, 4-453 
pdating region, client area, (vol. 1) 1-38 
ser-defined control window, (vol. 2) 8-34 
ser-defined resource, (vol. 2) 8-3 

User-defined resource statement, (vol. 2) 8-3 to 8-4 
User-defined variable, (vol. 2) 13-8, 14-7 


V 


ValidateCodeSegments function, (vol. 1) 3-14, 4-454 
ValidateFreeSpaces function, (vol. 1) 3-14, 4-454 
ValidateRect function, (vol. 1) 1-32, 4-455 
ValidateRgn function, (vol. 1) 1-32, 4-455 
Variable 

environmental, INCLUDE, (vol. 2) 8-47 

external, (vol. 2) 14-11 

frame, (vol. 2) 14-12 

global, (vol. 2) 14-11 

local, (vol. 2) 13-8 

names defined, (vol. 2) 14-7 

public, (vol. 2) 14-11 

size, (vol. 2) 14-12 

user-defined, (vol. 2) 13-8, 14-7 
Variable-pitch font attribute, (vol. 1) 2-35 
Vertical bar (I), as document convention, (vol. 1) xxv, 
(vol. 2) x 
VERTRES device capability, (vol. 1) 4-167 
VERTSIZE device capability, (vol. 1) 4-167 
Viewport 

extents, default, (vol. 1) 1-33 

origin, default, (vol. 1) 1-33 
Virtual-key character, (vol. 2) 8-7 
Virtual-key codes, (vol. 2) A-1 to A-5 
Virtual keys, (vol. 1) 1-4 
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VkKeyScan function, (vol. 1) 1-31, 4-456 
void data type, (vol. 2) 7-5 


W 


WaitMessage function, (vol. 1) 1-2, 4-457 
WaitSoundState function, (vol. 1) 3-12, 4-457 
WH_CALLWNDPROC windows-hook type, (vol. 1) 
4-419, 4-448 
WH_GETMESSAGE windows-hook type, (vol. 1) 
4-419, 4-448 
WH_JOURNALPLAYBACK windows-hook type, (vol. 
1) 4-419, 4-448 
WH_JOURNALRECORD windows-hook type, (vol. 1) 
4-419, 4-448 
WH_KEYBOARD windows-hook type, (vol. 1) 1-64, 
4-419, 4-448 
WH_MSGFILTER windows-hook type, (vol. 1) 1-64, 
4-419, 4-449 
WH_SYSMSGFILTER windows-hook type, (vol. 1) 
4-419 
WHITE_BRUSH stock object, (vol. 1) 4-207 
WHITE_PEN stock object, (vol. 1) 4-207 
WHITENESS raster-operation code, (vol. 1) 4-19 
WHITEONBLACK stretching mode, (vol. 1) 4-399 
?WIN option, Cmacro, (vol. 2) 13-4 
WINDING filling mode, (vol. 1) 4-58, 4-389 
WINDING polygon-filling mode, (vol. 1) 4-58, 4-197, 
4-389 
Window 
background, (vol. 1) 1-38 
background brush, (vol. 1) 1-11 
border, (vol. 2) 8-16 
brush alignment, (vol. 1) 1-39 
child, (vol. 2) 8-16 
close box, (vol. 1) 1-25 
described, (vol. 1) 1-23 
ID, (vol. 1) 1-23 
input, (vol. 1) 1-23 
messages, (vol. 1) 1-23 
overlapping, (vol. 1) 1-24 
owner window, (vol. 1) 1-23 
showing, (vol. 1) 1-23 
class 
attributes, (vol. 1) 1-10 
background brush, (vol. 1) 1-11, 1-13 
cursor, icon, attributes, (vol. 1) 1-10 
described, (vol. 1) 1-8 
functions, (vol. 1) 1-10 
instance handle, (vol. 1) 1-10 
menu, (vol. 1) 1-11, 1-14 
name, (vol. 1) 1-10 
unregistering, (vol. 1) 4-452 


control, user-defined, (vol. 2) 8-34 
creating, (vol. 1) 4-76, (vol. 2) 7-21, 8-15 
dialog box, (vol. 1) 1-43 
disabled, (vol. 2) 8-14, 8-16 
extents, default, (vol. 1) 1-34 
function. See Window function 
icon, (vol. 1) 1-22 
iconic, (vol. 2) 8-17 
main, creating, (vol. 1) 1-27 
MDI, (vol. 1) 1-25 
open, (vol. 1) 1-22 
origin, default, (vol. 1) 1-34 
overlapped, (vol. 1) 1-22 
overlapping, (vol. 1) 1-22, (vol. 2) 8-17 
owner, describing, (vol. 1) 1-23 
painting rectangles, (vol. 1) 1-39 
pop-up 
creating and showing, (vol. 1) 1-23 
style, (vol. 2) 8-17 
scroll bars, (vol. 1) 1-25 
size, (vol. 2) 8-17 
state, (vol. 1) 1-27 
style, dialog box, (vol. 2) 8-15 
styles 
child, (vol. 1) 1-22 to 1-23 
described, (vol. 1) 1-21 
listing, (vol. 2) 8-15 
owned, (vol. 1) 1-22 
pop-up, (vol. 1) 1-23 
state, (vol. 1) 1-27 
WS_CHILD, (vol. 2) 8-14 
subclassing, (vol. 1) 1-16, 4-368, 4-416 
System menu box, (vol. 1) 1-25 
title bar, (vol. 1) 1-25 
visible, (vol. 2) 8-18 
window-function address, (vol. 1) 1-12 
zoom, (vol. 2) 8-17 
Window applications 
application queue, (vol. 1) 1-3 
dispatching messages, (vol. 1) 1-3 
pulling messages, (vol. 1) 1-3 
pushing messages, (vol. 1) 1-3 
reading messages, (vol. 1) 1-3 
yielding control, (vol. 1) 1-3 
Window bar menu, (vol. 1) 1-25 
Window function 
address, (vol. 1) 1-12 
receiving messages, (vol. 1) 1-3 
role, (vol. 1) 1-6 
Window manager interface, defined, (vol. 1) xvi 
WindowFromPoint function, (vol. 1) 1-58, 2-20, 4-458 
Windows 
classes, locating, (vol. 1) 1-9 
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displaying functions, (vol. 1) 1-28 
enumerating for a task, (vol. 1) 4-123 
epilog, (vol. 2) 13-4 
library, (vol. 2) 13-5 
painting 
drawing, (vol. 1) 1-39 
filling, (vol. 1) 1-39 
inverting, (vol. 1) 1-39 
posting messages to a task, (vol. 1) 4-335 
prolog, (vol. 2) 13-4 
subclassing, (vol. 1) 1-16 
Windows debugging messages, (vol. 2) C-1 to C-11 
Windows prolog/epilog, Cmacro, (vol. 2) 13-4 
WINDOWS.H initialization file, (vol. 2) 8-15 
WinExec function, (vol. 1) 3-15, 4-458 to 4-459 
WinHelp function, (vol. 1) 3-15, 4-460 to 4-461 
WinMain function 
in assembly-language application, (vol. 2) 13-5 
main loop, (vol. 1) 1-4 
WINMEM32.DLL library, (vol. 2) E-1, E-3, E-9 
WM_ACTIVATE message, (vol. 1) 5-2, 6-47 
WM_ACTIVATEAPP message, (vol. 1) 5-2, 6-47 
WM_ASKCBFORMATNAME message, (vol. 1) 5-7, 
6-48 
WM_CANCELMODE message, (vol. 1) 5-2, 6-48 
WM_CHANGECBCHAIN message, (vol. 1) 5-7, 6-49 
WM_CHAR message, (vol. 1) 5-5, 6-49 
WM_CHARTOITEM message, (vol. 1) 5-5, 6-50 
WM_CHILDACTIVATE message, (vol. 1) 5-2, 6-51 
WM_CLEAR message, (vol. 1) 5-11, 6-51 
WM_CLOSE message, (vol. 1) 1-28, 5-2, 6-51 
WM_COMMAND message, (vol. 1) 5-5, 6-52, (vol. 2) 
7-17, 8-7 
WM_COMMAND notification codes. See Notification 
codes 
WM_COMPACTING message, (vol. 1) 5-8, 6-52 
WM_COMPAREITEM message, (vol. 1) 5-15, 6-53, 
(vol. 2) 7-19 
WM_COPY, (vol. 1) 5-11, 6-54 
WM_CREATE message, (vol. 1) 4-76, 5-2, 6-54 
WM_CTLCOLOR message, (vol. 1) 5-2, 6-54 
WM_CUT message, (vol. 1) 5-11, 6-55 
WM_DDE_ACK message, (vol. 2) 15-6 to 15-7 
WM_DDE_ADVISE message, (vol. 2) 15-8 to 15-9 
WM_DDE_DATA message, (vol. 2) 15-10 to 15-11 
WM_DDE_EXECUTE message, (vol. 2) 15-12 
WM_DDE_INITIATE message, (vol. 2) 15-13 
WM_DDE_POKE message, (vol. 2) 15-14 to 15-15 
WM_DDE_REQUEST message, (vol. 2) 15-16 
WM_DDE_TERMINATE message, (vol. 2) 15-17 
WM_DDE_UNADVISE message, (vol. 2) 15-17 to 15-18 
WM_DEADCHAR message, (vol. 1) 5-5, 6-55 to 6-56 
WM_DELETEITEM message, (vol. 1) 5-15, 6-8, 6-13, 


6-34, 6-40, 6-57, (vol. 2) 7-26 

WM_DESTROY message, (vol. 1) 1-28, 5-2, 6-57 
WM_DESTROYCLIPBOARD message, (vol. 1) 5-7, 
6-57 

WM_DEVMODECHANGE message, (vol. 1) 5-8, 6-58 
WM_DRAWCLIPBOARD message, (vol. 1) 5-7, 6-58 
WM_DRAWITEM message, (vol. 1) 5-15, 6-58, (vol. 2) 
7-36 

WM_ENABLE message, (vol. 1) 5-2, 6-59 
WM_ENDSESSION message, (vol. 1) 5-2, 6-59 
WM_ENTERIDLE message, (vol. 1) 5-2, 6-60, (vol. 2) 
7-33 

WM_ERASEBKGND message, (vol. 1) 5-2, 6-60 
WM_FONTCHANGE message, (vol. 1) 5-8, 6-61 
WM_GETDLGCODE message, (vol. 1) 5-2, 6-61 
WM_GETFONT message, (vol. 1) 5-9, 6-62 
WM_GETMINMAXINFO message, (vol. 1) 5-3, 6-63 
WM_GETTEXT message, (vol. 1) 5-3, 6-64 
WM_GETTEXTLENGTH message, (vol. 1) 5-3, 6-64 
WM_HSCROLL message, (vol. 1) 1-25, 5-5, 5-17, 6-65 
WM_HSCROLLCLIPBOARD message, (vol. 1) 5-7, 
6-66 

WM_ICONERASEBKGND message, (vol. 1) 5-3, 6-66 
WM_INITDIALOG message, (vol. 1) 4-43 to 4-44, 4-98 
to 4-99, 5-4, 6-67, 6-80 

WM_INITMENU message, (vol. 1) 5-4, 6-67 
WM_INITMENUPOPUP message, (vol. 1) 5-4, 6-68 
WM_KEYDOWN message, (vol. 1) 5-5, 6-68 to 6-69 
WM_KEYUP message, (vol. 1) 5-5, 6-70 
WM_KILLFOCUS message, (vol. 1) 5-3, 6-71 
WM_LBUTTONDBLCLK message, (vol. 1) 5-5, 6-71 
WM_LBUTTONDOWN message, (vol. 1) 5-5, 6-72 
WM_LBUTTONUP message, (vol. 1) 5-5, 6-72 
WM_MBUTTONDBLCLK message, (vol. 1) 5-5, 6-73 
WM_MBUTTONDOWN message, (vol. 1) 5-5, 6-74 
WM_MBUTTONUP message, (vol. 1) 5-5, 6-74 
WM_MDIACTIVATE message, (vol. 1) 5-19, 6-75 
WM_MDICASCADE message, (vol. 1) 5-19, 6-75 
WM_MDICREATE message, (vol. 1) 5-19, 6-75 
WM_MDIDESTROY message, (vol. 1) 5-19, 6-76 
WM_MDIGETACTIVE message, (vol. 1) 5-19, 6-77 
WM_MDIICONARRANGE message, (vol. 1) 5-20, 6-77 
WM_MDIMAXIMIZE message, (vol. 1) 5-20, 6-77 to 
6-78 

WM_MDINEXT message, (vol. 1) 5-20, 6-78 
WM_MDIRESTORE message, (vol. 1) 5-20, 6-78 
WM_MDISETMENU message, (vol. 1) 5-20, 6-79 
WM_MDITILE message, (vol. 1) 5-20, 6-79 
WM_MEASUREITEM message, (vol. 1) 5-15, 6-79, 
(vol. 2) 7-48 

WM_MENUCHAR message, (vol. 1) 5-3, 6-80 
WM_MENUSELECT message, (vol. 1) 5-3, 6-81 
WM_MOUSEACTIVATE message, (vol. 1) 5-5, 6-82 
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WM_MOUSEMOVE message, (vol. 1) 5-5, 6-82 
WM_MOVE message, (vol. 1) 5-3, 6-83 
WM_NCACTIVATE message, (vol. 1) 5-18, 6-75, 6-83 
WM_NCCALCSIZE message, (vol. 1) 5-18, 6-83 
WM_NCCREATE message, (vol. 1) 5-18, 6-84 
WM_NCDESTROY message, (vol. 1) 5-18, 6-84 
WM_NCHITTEST message, (vol. 1) 5-18, 6-85 
WM_NCLBUTTONDBLCLK message, (vol. 1) 5-18, 
6-86 

WM_NCLBUTTONDOWN message, (vol. 1) 5-18, 6-86 
WM_NCLBUTTONUP message, (vol. 1) 5-18, 6-87 
WM_NCMBUTTONDBLCLK message, (vol. 1) 5-18, 
6-87 

WM_NCMBUTTONDOWN message, (vol. 1) 5-18, 6-88 
WM_NCMBUTTONUP message, (vol. 1) 5-18, 6-88 
WM_NCMOUSEMOVE message, (vol. 1) 5-19, 6-88 
WM_NCPAINT message, (vol. 1) 5-19, 6-89 
WM_NCRBUTTONDBLCLK message, (vol. 1) 5-19, 
6-89 

WM_NCRBUTTONDOWN message, (vol. 1) 5-19, 6-90 
WM_NCRBUTTONUP message, (vol. 1) 5-19, 6-90 
WM_NEXTDLGCTL message, (vol. 1) 5-9, 6-90 
WM_PAINT message, (vol. 1) 1-37, 5-3, 6-91 
WM_PAINTCLIPBOARD message, (vol. 1) 5-7, 6-91 
WM_PAINTICON message, (vol. 1) 5-3, 6-92 
WM_PALETTECHANGED message, (vol. 1) 5-8, 6-92 
WM_PARENTNOTIPFY message, (vol. 1) 5-3, 6-93 
WM_PASTE message, (vol. 1) 5-11, 6-94 
WM_QUERYDRAGICON message, (vol. 1) 5-3, 6-94 
WM_QUERYENDSESSION message, (vol. 1) 5-3, 6-94 
WM_QUERYNEWPALETTE message, (vol. 1) 5-3, 6-95 
WM_QUERYOPEN message, (vol. 1) 5-4, 6-95 
WM_QUIT message, (vol. 1) 1-28, 5-4, 6-96 
WM_RBUTTONDBLCLK message, (vol. 1) 5-6, 6-96 
WM_RBUTTONDOWN message, (vol. 1) 5-6, 6-97 
WM_RBUTTONUP message, (vol. 1) 5-6, 6-97 
WM_RENDERALLFORMATS message, (vol. 1) 5-7, 
6-98 

WM_RENDERFORMAT message, (vol. 1) 5-7, 6-98 
WM_SETCURSOR message, (vol. 1) 5-6, 6-98 
WM_SETFOCUS message, (vol. 1) 5-4, 6-99 
WM_SETFONT message, (vol. 1) 5-4, 5-9, 6-99, (vol. 2) 
7-32 

WM_SETREDRAW message, (vol. 1) 5-4, 6-100 
WM_SETTEXT message, (vol. 1) 5-4, 6-100 
WM_SHOWWINDOW message, (vol. 1) 5-4, 6-101 
WM_SIZE message, (vol. 1) 5-4, 6-102 
WM_SIZECLIPBOARD message, (vol. 1) 5-7, 6-102 
WM_SPOOLERSTATUS message, (vol. 1) 5-8, 6-103 
WM_SYSCHAR message, (vol. 1) 5-6, 6-103 to 6-104 
WM_SYSCOLORCHANGE message, (vol. 1) 5-8, 6-105 
WM_SYSCOMMAND message, (vol. 1) 5-6, 6-105 to 
6-106, (vol. 2) 8-7 


WM_SYSDEADCHAR message, (vol. 1) 5-6, 6-107 
WM_SYSKEYDOWN message, (vol. 1) 5-6, 6-107 
WM_SYSKEYUP message, (vol. 1) 5-7, 6-108 to 6-109 
WM_SYSMENU window style, (vol. 2) 7-32 
WM_TIMECHANGE message, (vol. 1) 5-8, 6-110 
WM_TIMER message, (vol. 1) 5-6, 6-110 

WM_UNDO message, (vol. 1) 5-11, 6-111 

WM_USER message, (vol. 1) 6-1 

WM_VKEYTOITEM message, (vol. 1) 5-6, 6-111 
WM_VSCROLL message, (vol. 1) 1-25, 5-6, 5-17, 6-112 
WM_VSCROLLCLIPBOARD message, (vol. 1) 5-7, 
6-113 

WM_WININICHANGE message, (vol. 1) 5-8, 6-114 
WNDCLASS data structure, (vol. 1) 4-153, (vol. 2) 7-62 
to 7-67 

WORD alignment type, (vol. 2) 14-5 

WORD data type, (vol. 2) 7-5 

Wordwrap, (vol. 2) 8-40 

WriteComm function, (vol. 1) 3-11, 4-462 
WritePrivateProfileS tring function, (vol. 1) 3-10, 4-462 
to 4-463 

WriteProfileString function, (vol. 1) 3-10, 4-464 
WS_BORDER window style, (vol. 1) 4-66, (vol. 2) 8-16, 
8-26, 8-32 

WS_CAPTION window style, (vol. 1) 1-25, 1-45, 4-66, 
6-76, (vol. 2) 7-32, 8-16 

WS_CHILD window style, (vol. 1) 1-23, 4-66, 6-76, 
(vol. 2) 8-14, 8-16 

WS_CHILDWINDOW window style, (vol. 1) 4-66, (vol. 
2) 8-16 

WS_CLIPCHILDREN window style, (vol. 1) 4-66, 6-76, 
(vol. 2) 8-16 

WS_CLIPSIBLINGS window style, (vol. 1) 4-66, 6-76, 
(vol. 2) 8-16 

WS_DISABLED window style, (vol. 1) 4-67, (vol. 2) 
8-16, 8-25, 8-27, 8-29 to 8-31 

WS_DLGFRAME window style, (vol. 1) 4-67, (vol. 2) 
8-16 

WS_EX_DLGMODALFRAME extended window style, 
(vol. 1) 4-77 

WS_EX_NOPARENTNOTIFY extended window style, 
(vol. 1) 4-77 

WS_GROUP window style, (vol. 1) 4-67, (vol. 2) 8-17, 
8-21 to 8-25, 8-29 to 8-31 

WS_HSCROLL window style, (vol. 1) 4-67, (vol. 2) 
7-48, 8-17, 8-31 

WS_ICONIC window style, (vol. 1) 4-67, (vol. 2) 8-17 
WS_MAXIMIZE window style, (vol. 1) 4-67, (vol. 2) 
7-48, 8-17 

WS_MAXIMIZEBOX window style, (vol. 1) 4-67, 6-76, 
(vol. 2) 8-17 

WS_MINIMIZE window style, (vol. 1) 4-67, (vol.-2) 
7-48, 8-17 
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WS_MINIMIZEBOX window style, (vol. 1) 4-67, (vol. 
2) 8-17 

WS_OVERLAPPED window style, (vol. 1) 1-22, 4-67, 
(vol. 2) 8-17 

WS_OVERLAPPEDWINDOW window style, (vol. 1) 
1-22, 4-67, (vol. 2) 8-17 

WS_POPUP window style, (vol. 1) 1-23, 4-67, (vol. 2) 
8-17 

WS_POPUPWINDOW window style, (vol. 1) 4-67, (vol. 
2) 8-17 

WS_SIZEBOX window style, (vol. 2) 8-17 
WS_SYSMENU window style, (vol. 1) 1-25, 1-45, 4-66 
to 4-67, 6-76, (vol. 2) 8-16 to 8-17 

WS_TABSTOP window style, (vol. 1) 4-67, (vol. 2) 
8-17, 8-21 to 8-25, 8-27, 8-29 to 8-31 
WS_THICKFRAME window style, (vol. 1) 4-68, 6-76, 
(vol. 2) 8-18 

WS_VISIBLE window style, (vol. 1) 4-68, (vol. 2) 8-18 
WS_VSCROLL window style, (vol. 1) 4-68, (vol. 2) 
7-48, 8-18, 8-26, 8-31 to 8-32 

wsprintf function, (vol. 1) 3-9, 4-465 to 4-466 
wvsprintf function, (vol. 1) 3-9, 4-467 to 4-468 
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Yield function, (vol. 1) 3-7, 4-469 to 4-470 
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